Suparagent: đồng nghiệp AI xin 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à không gian làm việc mã nguồn mở, cho bạn tạo các “đồng nghiệp AI” có tên, nhiệm vụ, trí nhớ và lịch chạy riêng, và chỉ hành động khi bạn duyệt. Bạn dùng bản desktop hoặc tự host server. Cài bản desktop từ mã nguồn cần Node.js 22+, uv và một engine AI có sẵn; README ghi chỉ ba lệnh để chạy.
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. Mỗi đồng nghiệp có một nhiệm vụ, một thư mục làm việc, trí nhớ và quy tắc xin phép của riêng nó. Mọi cuộc trò chuyện, ghi chú, lịch chạy và yêu cầu duyệt nằm chung một chỗ, trên máy bạn hoặc trên server bạn tự quản.
Repo này hợp với người muốn giao việc lặp lại cho AI nhưng vẫn muốn nắm quyền kiểm soát. Ví dụ: chủ shop cần bản tổng hợp hằng tuần, nhân viên văn phòng cần soạn báo cáo từ một đống ghi chú, hoặc 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 7041 sao và 913 fork, giấy phép Apache-2.0, viết chủ yếu bằng Python.
Điểm đáng giá nhất là hai chữ “duyệt trước”. Bạn chọn mức tự do cho từng agent, từ “Ask first” (hỏi trước khi làm) đến “Plan only” (chỉ lập kế hoạch). Một routine chạy theo lịch cũng không bao giờ tự duyệt hành động thay bạn. Bạn 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ở cho đồng nghiệp AI: mỗi agent có tên, nhiệm vụ, trí nhớ, lịch chạy và chờ 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ế.
- 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. 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 trong phòng chung. Lợi ích: bạn không phải nhồi mọi thứ vào một cuộc chat dài. README ghi trưởng nhóm cần dùng Claude hoặc Codex.
- Giữ ngữ cảnh. Agent có thể lưu ghi chú, nhớ lại ghi chú và hội thoại liên quan, và tìm trong lịch sử. Bạn xem và sửa được những gì nó nhớ. Lợi ích: lần sau bạn không phải giải thích lại từ đầu.
- Chạy theo lịch (routine). Routine chạy theo lịch, qua webhook hoặc bấm tay. Bạn xem từng kết quả và trả lời các yêu cầu duyệt.
- Chọn mức tự do. Có các 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 ngay trong app.
- Kết nối công cụ. Bạn nối GitHub, Gmail, Google Calendar… qua khoá Composio của chính bạn, 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 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òn hiện được thư 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ử.
- Tái sử dụng chỉ 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.
- Dùng trên đ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ụ.
- 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 để chép lời (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ử.
Lưu ý quan trọng: Suparagent không kèm sẵn mô hình AI hay gói đăng ký mô hình. Bạn tự mang engine và tài khoản nhà cung cấp.
II.Cần chuẩn bị gì
Theo README, bản desktop chạy từ một thư mục 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 docs.astral.sh/uv).
- Ít nhất một engine có sẵn trên cùng máy tính.
- Git để tải mã về (lệnh
git clonephổ thông).
Về engine, bạn có các lựa chọn sau:
- Một công cụ dòng lệnh như Claude Code, Codex CLI, Gemini CLI, Cursor hoặc agent khác dùng giao thức ACP. Với loại này, bạn phải cài và đăng nhập nó trước khi mở Suparagent.
- Hoặc cấu hình một engine dùng API trong Settings → Engines: OpenRouter, hoặc API tương thích OpenAI như Ollama hay LM Studio.
Docker chỉ cần khi bạn muốn dùng “máy tính cô lập” cho agent, và tính năng này còn thử nghiệm. README không nói rõ yêu cầu phần cứng hay hệ điều hành cụ thể cho bản desktop, nên mình không nêu ở đây. Nếu tự host server, bảng so sánh trong README ghi cần máy chủ Linux, HTTPS, và Docker hoặc Node.js cùng uv.
Suparagent không gồm mô hình AI. Dùng engine của nhà cung cấp bên ngoài có thể tốn tiền theo mức dùng của tài khoản đó. Hãy kiểm tra gói cước của engine trước khi giao việc lặp lại cho agent.
III.Cài đặt từng bước
- Chuẩn bị công cụCài Node.js 22+, uv và một engine AI đã đăng nhập
- Tải mã nguồnDùng git clone để lấy repo về máy
- Vào thư mục desktopcd vào suparagent/desktop
- Chạy ứng dụngGõ npm run app
- Cấu hình lần đầuChọn engine, workspace và chế độ duyệt
A.Chuẩn bị Node.js, uv và engine
README không đưa lệnh cài Node.js hay uv, nên bạn làm theo trang chủ của từng công cụ. Với uv, README dẫn tới trang docs.astral.sh/uv. Nếu dùng engine dạng dòng lệnh (ví dụ Claude Code hay Codex CLI), hãy cài và đăng nhập nó trước. Đây là chỗ người mới hay vấp nhất: mở Suparagent khi engine chưa đăng nhập thì app sẽ không có gì để trả lời bạn.
B.Tải mã nguồn
Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) ở thư mục bạn muốn đặt dự án, rồi chạy:
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.
C.Vào thư mục desktop và chạy
cd suparagent/desktop
npm run appLệnh đầu đưa terminal vào thư mục desktop. Lệnh thứ hai khởi chạy ứng dụng, và đây đúng là lệnh README ghi. README không nhắc thêm bước cài gói nào khác. Nếu lệnh báo thiếu gói, hãy xem hướng dẫn thiết lập desktop trong thư mục docs/ của repo, vì README không nói gì thêm.
Repo có kèm 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 cách dùng.
D.Cấu hình lần đầu
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 thứ tự README gợi ý:
- 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 nhiệm vụ rõ ràng và một workspace.
- Bắt đầu chat. Chọn Ask first để app dừng chờ 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.
Về các cách chạy khác: README có nhắc bản cài đặt (installer) trên trang Releases, nhưng ghi rõ chúng còn thử nghiệm và chưa ký số. Muốn tự host server, README chỉ tới hướng dẫn self-hosting trong repo, và repo có Dockerfile cùng compose.yaml. README chính không ghi lệnh Docker cụ thể, nên bạn đọc hướng dẫn self-hosting trong thư mục docs/ thay vì đoán lệnh.
IV.Kiểm tra đã chạy được chưa
README không mô tả một lệnh kiểm tra riêng. Dấu hiệu hợp lý nhất theo các bước của README là:
- Cửa sổ ứng dụng mở ra và cho bạn chọn engine, workspace, chế độ duyệt.
- Trong Settings → Engines, engine bạn dùng hiện 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 một việc cần duyệt, app dừng lại và hỏi bạn.
Nếu engine không sẵn sàng, quay lại mục Engines để xem nó báo gì, rồi xem phần lỗi bên dưới.
V.Dùng vào việc thật
Dưới đây là vài tình huống bám sát khả năng README nêu.
A.Tổng hợp báo cáo dự án hằng tuần
Bối cảnh: bạn là nhân viên văn phòng, mỗi tuần phải gom ghi chú và báo cáo rời rạc thành một bản tóm tắt gửi sếp. README có đúng ví dụ này.
Cách làm: tạo một agent trưởng nhóm và hai chuyên viên, chẳng hạn một người nghiên cứu và một người biên tập. 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ắn cho trưởng nhóm một câu như:
Hãy soạn bản tóm tắt tuần này từ các ghi chú và báo cáo trong thư mục dự án.Kết quả: trưởng nhóm tách việc nhỏ, giao cho chuyên viên, các cuộc trò chuyện riêng chạy xong rồi trả về để trưởng nhóm ghép lạ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 có nghĩa là mất quyền quyết định: mọi hành động quan trọng vẫn chờ bạn bấm duyệt.
Ông T
B.Biến việc đã ổn thành routine
Bối cảnh: quy trình tóm tắt tuần ở trên đã chạy tốt vài lần, và bạn chán phải nhắn lại mỗi tuần.
Cách làm: tạo một routine chạy theo lịch hằng tuần, hoặc kích hoạt bằng webhook hay bấm tay. README lưu ý routine chạy ở backend, nên backend phải luôn chạy; nếu tắt máy thì lịch không chạy. Kết quả: mỗi lần chạy xong, bạn xem kết quả trong app và trả lời các yêu cầu duyệt, vì routine không tự duyệt thay bạn.
C.Bắt đầu ngày bằng màn hình Today
Bối cảnh: bạn là chủ shop nhỏ, có nhiều agent đang làm việc và không biết cái nào đang chờ mình.
Cách làm: mở màn hình Today. Nó gom 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ếu đã nối Gmail và lịch (chỉ đọc), bạn cũng thấy thư và lịch ở đây. Kết quả: bạn xử lý hết những thứ đang kẹt chỉ trong vài phút, thay vì lần lượt mở từng cuộc chat.
D.Duyệt việc từ điện thoại
Bối cảnh: bạn ra ngoài, agent đang chờ cho phép một lệnh gọi công cụ.
Cách làm: ghép app điện thoại với server của bạn. Trên đó bạn chat, dừng câu trả lời, cho phép hoặc từ chối công cụ. Giới hạn: README nói app mới thử trên máy giả lập Android và một điện thoại Android, chưa thử iOS, chưa có thông báo đẩy hay bản phát hành trên kho ứng dụng.
VI.Lỗi hay gặp và cách xử lý
Engine không sẵn sàng. Nguyên nhân thường gặp là công cụ dòng lệnh chưa cài hoặc chưa đăng nhập. README yêu cầu cài và đăng nhập trước khi mở app. Cách xử lý: đăng nhập engine trong terminal, rồi vào Settings → Engines kiểm tra lại. Hoặc cấu hình một engine API tại đó.
Lệnh npm run app báo lỗi. Có thể bạn đang đứng sai thư mục, hoặc Node.js cũ hơn 22. Hãy chắc là bạn đã cd suparagent/desktop và chạy node --version để kiểm tra phiên bản. Thiếu uv cũng là một nguyên nhân dễ xảy ra. Nếu vẫn lỗi, tìm trong GitHub Issues của repo hoặc hỏi ở cộng đồng Discord.
Routine không chạy đúng giờ. README nói routine chạy ở backend nên backend phải luôn chạy. Nếu bạn tắt máy hay đóng ứng dụng, lịch sẽ không chạy. Hãy để máy hoặc server chạy liên tục khi cần lịch ổn định.
Agent không dùng được ứng dụng đã kết nối. README ghi chỉ agent Claude và Codex dùng được các app kết nối qua Composio. Hãy kiểm tra engine của agent đó và đã cấp quyền cho đúng agent chưa. Các thay đổi vẫn chờ bạn duyệt, nên đừng nhầm “đang chờ” với “bị lỗi”.
Installer không cài được hoặc cảnh báo bảo mật. README nói installer còn 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 ngại, dùng cách chạy từ mã nguồn ở trên.
VII.Có nên dùng không
Điểm mạnh:
- Mã nguồn mở, giấy phép Apache-2.0, bạn tự giữ dữ liệu. Với desktop và self-host, hội thoại, ghi chú, routine và cài đặt nằm trong thư mục dữ liệu hoặc cơ sở dữ liệu của chính bạn. Khoá API lưu qua Suparagent được mã hoá.
- Linh hoạt về engine: Claude Code, Codex, Gemini CLI, Cursor, OpenRouter, Ollama, LM Studio…
- Thiết kế quanh sự kiểm soát: mọi hành động cần duyệt đều chờ bạn.
Giới hạn cần biết trước:
- Dự án đang phát triển, bản desktop và self-host đều ghi là thử nghiệm. README khuyên cân nhắc kỹ trước khi dùng cho việc quan trọng.
- Khi agent trả lời, engine bạn chọn nhận câu lệnh và ngữ cảnh cần thiết, có thể gồm tệp đính kèm, ghi chú và nội dung thư mục. Nếu engine là dịch vụ trên mạng, dữ liệu đó theo điều khoản của nhà cung cấp.
- Lãnh đạo nhóm phải dùng Claude hoặc Codex; app điện thoại chưa thử trên iOS; phần Docker, công cụ trình duyệt, MCP Marketplace và một số tính năng khác vẫn chưa kiểm định đầy đủ.
- Máy chủ tự host phục vụ một chủ sở hữu và những người họ mời, không phải dịch vụ nhiều tổ chức.
- Bản hosted trên suparagent.ai là sản phẩm riêng, có gói trả phí; phần này khác với bản mã nguồn mở bạn tự chạy.
Nên chọn nếu bạn muốn thử cách làm việc với nhiều agent, có lịch chạy và quyền duyệt rõ ràng, và chấp nhận phần mềm còn mới. Nếu bạn cần một công cụ đã ổn định hoàn toàn, có ký số và hỗ trợ iOS, hãy chờ thêm hoặc chọn giải pháp trưởng thành hơn.
Câu hỏi thường gặp
Suparagent có miễn phí không?
Phần mã nguồn mở (bản desktop và self-host) dùng giấy phép Apache-2.0. Tuy vậy Suparagent không kèm mô hình AI, nên bạn tự mang tài khoản nhà cung cấp và có thể tốn tiền theo mức dùng. Bản hosted trên suparagent.ai là sản phẩm riêng, có gói từ miễn phí xem thử đến các gói trả phí.
Cần cài những gì trước khi chạy?
README ghi bản desktop 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. Với engine dòng lệnh, bạn phải cài và đăng nhập trước. Docker chỉ cần khi dùng máy tính cô lập cho agent, và tính năng này còn thử nghiệm.
Có chạy được trên Windows không?
README không nêu rõ hệ điều hành cho bản desktop, nên mình không khẳng định. Repo có tệp run-desktop.bat và README nhắc các installer desktop còn thử nghiệm, chưa ký số, nền tảng được kiểm chứng còn 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.
Dữ liệu của tôi có an toàn không?
Với bản desktop và self-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 bạn, và khoá API lưu qua Suparagent được mã hoá. Tuy nhiên khi agent trả lời, engine bạn chọn nhận câu lệnh và ngữ cảnh cần thiết. Nếu engine là dịch vụ trên mạng, thông tin đó theo điều khoản của nhà cung cấp.
Cần GPU không?
README không nêu yêu cầu GPU. Suparagent không kèm mô hình, mà kết nối tới engine bạn chọn như Claude Code, Codex, OpenRouter hoặc API tương thích OpenAI như Ollama và LM Studio. Phần cứng cần thiết sẽ phụ thuộc vào engine bạn dùng.
Agent có tự làm việc mà không hỏi tôi không?
Tuỳ chế độ bạn chọn: Ask first, Accept edits, Approve for me (cho Claude, Codex, Cursor) hoặc Plan only. README nhấn mạnh routine chạy theo lịch không bao giờ tự duyệt hành động thay bạn. Với các app kết nối qua Composio, thay đổi cũng chờ bạn duyệt.
Dự án có ổn định để dùng cho việc quan trọng chưa?
README ghi rõ dự án đang phát triển tích cực, bản desktop và self-host còn thử nghiệm, và khuyên xem kỹ phần giới hạn trước khi dựa vào nó cho việc quan trọng. Một số tính năng như Docker, MCP Marketplace chưa được kiểm định đầy đủ.


