Suparagent: lập đội đồng nghiệp AI tự chạy, hỏi bạn trước khi làm — hướng dẫn cài 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) cho phép bạn tạo các đồng nghiệp AI có tên, giao việc, lưu trí nhớ và đặt lịch chạy định kỳ. Bạn chạy nó trên máy mình hoặc tự host trên máy chủ, và mang theo công cụ AI sẵn có như Claude Code hay Codex. Cài bản desktop cần Node.js 22+, uv và một engine AI; các bước khá gọn nhưng dự án còn đang phát triển, ở mức thử nghiệm.
Suparagent là một không gian làm việc mã nguồn mở cho các «đồng nghiệp AI»: bạn tạo từng agent có tên riêng, 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. Toàn bộ hội thoại, trí nhớ, lịch chạy định kỳ và các lần xin duyệt được gom về một chỗ. Bạn có thể chạy 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 người muốn có «nhân viên AI» làm những việc lặp lại, như tổng hợp báo cáo hằng tuần, mà vẫn giữ quyền kiểm soát. Chủ shop, nhân viên văn phòng và lập trình viên mới đều dùng được, miễn là bạn đã có sẵn một công cụ AI (ví dụ Claude Code, Codex, hoặc một API) để làm «bộ não». Suparagent không kèm sẵn mô hình hay gói đăng ký nào.
Điểm đáng giá nhất là cơ chế duyệt: agent muốn làm gì có ảnh hưởng thì phải hỏi bạn trước, kể cả khi chạy theo lịch. Repo hiện có khoảng 7.041 sao và 913 fork. Xem video ngắn bên dưới để thấy giao diện thực tế trước khi cài.
Anil-matcha/suparagent
Suparagent là 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 chờ bạn duyệt trước khi hành động.
I.Suparagent làm được gì
Dưới đây là những tính năng chính, mình diễn giải theo lợi ích khi dùng.
- Tạo agent và lập đội. Mỗi agent có tên, vai trò, engine, thư mục làm việc, trí nhớ và mức duyệt riêng. Một agent «trưởng nhóm» có thể chia việc cho các agent chuyên môn, hoặc điều phối nhiều agent trong phòng chung. Trưởng nhóm hiện cần dùng Claude hoặc Codex.
- Nhớ ngữ cảnh. Agent có thể 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ì 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). 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; routine không bao giờ tự duyệt thay 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 (dành cho Claude, Codex, Cursor) và Plan only (chỉ lập kế hoạch). Mọi hoạt động công cụ và quyết định duyệt đều xem lại được trong app.
- Kết nối ứng dụng. Qua khoá Composio của chính bạn, có thể nối GitHub, Gmail, Google Calendar rồi cấp quyền cho các 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 các việc 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 ở 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 (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 để khỏi viết lại từ đầu.
- 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 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ử.
Về engine, bạn nối được 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. Không phải engine nào cũng hỗ trợ đủ tính năng; ví dụ nhập ảnh và máy tính riêng cho agent không có ở mọi engine.
II.Cần chuẩn bị gì
Theo README, để chạy bản desktop từ mã nguồn bạn cần:
- Node.js 22 trở lên.
- uv (công cụ quản lý Python; README dẫn tới trang tài liệu của uv để cài).
- Ít nhất một engine trên cùng máy. Nếu dùng engine dạng dòng lệnh (CLI), hãy cài và đăng nhập nó trước khi mở app. Nếu dùng engine qua API, bạn cấu hình trong Settings → Engines.
- Docker chỉ cần nếu bạn muốn dùng «máy tính riêng» (cô lập) cho agent. Đây là tính năng tuỳ chọn.
Bạn tự lo tài khoản nhà cung cấp AI và trả phí dùng mô hình cho họ (nếu có). Suparagent không bán mô hình.
Về hệ điều hành, README không liệt kê rõ cho bản chạy từ mã nguồn. Trong thư mục gốc có file run-desktop.bat, nhưng README không giải thích cách dùng nó, nên mình không khẳng định gì thêm. Bản cài đặt sẵn trên trang Releases được README nói là thử nghiệm, chưa ký số, và mới kiểm chứng nền tảng ở mức hạn chế.
Nếu muốn tự host trên máy chủ: README ghi cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine. Repo có sẵn Dockerfile và compose.yaml, còn các bước chi tiết nằm trong tài liệu self-hosting ở thư mục docs/ của repo.
III.Cài đặt từng bước
- Chuẩn bị Node.js, uv, engineCài Node.js 22+, uv và một engine AI (đã đăng nhập nếu là CLI)
- Tải mã nguồnDùng git clone để lấy repo về máy
- Chạy appVào thư mục desktop và chạy npm run app
- 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.Chuẩn bị Node.js, uv và engine
Cài Node.js phiên bản 22 trở lên và uv theo trang chủ của từng công cụ. README không đưa lệnh cài cho hai thứ này, nên bạn cứ làm theo hướng dẫn chính thức của chúng. Sau đó chuẩn bị engine: nếu bạn đã dùng Claude Code hoặc Codex CLI, hãy mở nó riêng một lần và đăng nhập xong rồi mới sang bước sau. Chỗ người mới hay vấp là quên đăng nhập engine, khiến app báo engine chưa sẵn sàng.
B.Tải mã nguồn về máy
Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux), đứng ở thư mục bạn muốn lưu 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. Máy bạn cần có Git.
C.Chạy ứng dụng desktop
Vào thư mục desktop bên trong repo rồi chạy lệnh theo README:
cd suparagent/desktop
npm run appĐiểm cần nhớ: lệnh npm run app phải chạy trong thư mục desktop, không phải thư mục gốc. Nếu chạy sai chỗ, npm sẽ báo không tìm thấy script.
D.Thiết lập lần đầu
Lần đầu mở, app yêu cầu bạn chọn engine, workspace (thư mục làm việc) và chế độ duyệt. Nếu chưa chắc, hãy chọn Ask first: agent sẽ dừng lại hỏi bạn trước những hành động cần duyệt. Đây là lựa chọn an toàn nhất khi mới làm quen.
E.Tạo agent đầu tiên
Làm theo thứ tự 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 thật rõ ràng và một workspace.
- Bắt đầu chat, chọn Ask first.
- Khi cần chia việc hoặc lặp lại việc, thêm đồng đội hoặc tạo routine.
Suparagent chỉ là «vỏ» điều phối. Mỗi lượt trả lời, engine bạn chọn nhận câu hỏi và ngữ cảnh cần thiết (văn bản đính kèm, ghi chú liên quan, nội dung tệp mà nó đọc). 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. Dùng engine có thể tốn tiền, nên bắt đầu với thư mục thử nghiệm và chế độ Ask first.
IV.Kiểm tra đã chạy được chưa
README không đưa một lệnh kiểm tra riêng, nhưng có các dấu hiệu rõ ràng:
- Cửa sổ ứng dụng mở lên sau khi chạy
npm run appvà hiện màn hình thiết lập lần đầu. - Trong Settings → Engines, engine của bạn hiện là đã sẵn sàng.
- Bạn tạo được một agent và nhắn một câu, agent trả lời. Khi chọn Ask first, những hành động cần quyền sẽ hiện yêu cầu duyệt để bạn đồng ý hoặc từ chối.
Cách thử nhanh: tạo agent trỏ tới một thư mục thử chứa vài tệp ghi chú, rồi nhờ nó tóm tắt. Nếu có câu trả lời và bạn xem được lịch sử trong app, bạn đã cài thành công.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo những gì README mô tả. Tên agent và câu lệnh mẫu là ví dụ của mình để bạn dễ hình dung.
A.Bản tin dự án mỗi tuần cho nhân viên văn phòng
Bạn quản lý một dự án, mỗi tuần có vài báo cáo và ghi chú rải rác trong một thư mục. Hãy tạo một agent trưởng nhóm, đặt engine là Claude hoặc Codex, cùng hai agent chuyên môn, ví dụ «Nghiên cứu» và «Biên tập». Cho cả ba dùng chung thư mục dự án. Rồi nhắn cho trưởng nhóm:
Hãy soạn bản tin tuần này từ các ghi chú và báo cáo trong thư mục dự án. Nhờ agent Nghiên cứu gom số liệu, agent Biên tập viết lại cho gọn.Trưởng nhóm chia nhỏ việc, giao cho các chuyên gia, mỗi người làm trong một cuộc trò chuyện riêng rồi trả kết quả về để trưởng nhóm rá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, và xem lại từng lần chạy trong app.
Routine không bao giờ tự duyệt thay bạn: AI làm việc lặp lại, còn quyền quyết định vẫn ở tay bạn.
Ông T
B.Buổi sáng của chủ shop: xem Today
Chủ shop nhỏ thường bị ngập trong email và lịch hẹn. Nếu bạn nối Gmail và Google Calendar qua khoá Composio của mình (và dùng agent Claude hoặc Codex), màn hình Today gom lại những thứ cần bạn: yêu cầu duyệt, câu hỏi từ agent, kết quả routine, việc đến hạn, và có thể hiện thư cùng lịch ở dạng chỉ đọc. Bạn mở một màn hình là biết hôm nay cần xử lý gì. Lưu ý README nói phần kết nối ứng dụng mới được thử với dịch vụ Composio giả lập, chưa phải dịch vụ thật, nên hãy thử trước với việc không quan trọng.
C.Lập trình viên mới: giao việc cho agent có kiểm soát
Bạn đang học và muốn AI hỗ trợ trong một thư mục dự án. Tạo agent, trỏ workspace vào thư mục đó và chọn Accept edits hoặc Ask first. Mỗi lần agent muốn sửa tệp hay gọi công cụ, bạn xem được hoạt động và quyết định duyệt trong app. Nếu chưa muốn nó đụng vào tệp nào, chọn Plan only để chỉ nhận kế hoạch. Cách này giúp bạn học cách AI làm việc mà không sợ mất mã nguồn.
D.Việc định kỳ chạy theo lịch hoặc webhook
Ví dụ bạn cần mỗi sáng thứ Hai có bản tóm tắt tuần trước. Tạo routine cho agent đó với lịch chạy hằng tuần, hoặc cho chạy bằng webhook khi có sự kiện, hoặc bấm tay khi cần. Kết quả hiện ra để bạn xem. Vì routine chạy trong backend, README nhắc rằng backend phải đang chạy thì lịch mới hoạt động. Nếu bạn tắt máy hoặc tắt app, lịch sẽ không chạy.
VI.Lỗi hay gặp và cách xử lý
Báo engine chưa sẵn sàng. Thường do bạn chưa cài hoặc chưa đăng nhập engine dạng CLI trên cùng máy. Hãy cài engine, đăng nhập xong rồi mở lại app, vào Settings → Engines kiểm tra. Nếu dùng API, kiểm tra lại cấu hình ở đúng mục này.
Lệnh npm run app không chạy. Hai nguyên nhân dễ gặp: đứng sai thư mục (phải là suparagent/desktop) hoặc Node.js cũ hơn bản 22. Hãy kiểm tra phiên bản Node.js của bạn rồi nâng cấp nếu cần. Cũng đảm bảo đã cài uv, 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 luôn chạy. Nếu bạn tắt app hoặc máy ngủ, lịch bị bỏ lỡ. Muốn chạy đều đặn thì cân nhắc tự host trên một máy chủ luôn bật, theo tài liệu self-hosting trong repo.
Agent không dùng được tính năng X. Không phải engine nào cũng hỗ trợ đủ: nhập ảnh, máy tính riêng cho agent, kết nối ứng dụng (chỉ Claude và Codex), hay làm trưởng nhóm (cũng cần Claude hoặc Codex). Xem bảng khả năng engine trong thư mục docs/ của repo rồi đổi engine cho phù hợp.
Bản cài đặt sẵn bị hệ điều hành cảnh báo. README nói các bộ cài desktop 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 như trên.
VII.Có nên dùng không
Điểm mạnh. Bạn giữ quyền kiểm soát: có nhiều mức duyệt, mọi hành động xem lại được, routine không tự duyệt. Dữ liệu bản desktop và self-host nằm trên máy hoặc máy chủ của bạn, khoá API lưu qua Suparagent được mã hoá. Bạn tự chọn engine, kể cả mô hình chạy cục bộ qua Ollama hoặc LM Studio. Mã nguồn mở theo Apache-2.0.
Giới hạn. README tự nói dự án còn đang phát triển và nhiều thứ ở mức thử nghiệm: bản cài desktop chưa ký số, máy chủ tự host chỉ có một chủ sở hữu (có thể mời đồng đội nhưng mọi người dùng chung agent, hội thoại, trí nhớ), phần giao việc theo đội còn mới. App điện thoại mới thử trên Android, chưa có iOS, chưa có thông báo đẩy. Docker computer, công cụ trình duyệt và bản macOS gốc đều là tuỳ chọn thử nghiệm. Kết nối ứng dụng qua Composio chưa được thử trên dịch vụ thật. Bạn cũng phải tự có engine và chịu chi phí model.
Khi nên chọn cách khác. Nếu bạn cần một dịch vụ ổn định, đã đóng gói sẵn, cho nhiều tổ chức, hoặc chỉ muốn chat đơn giản với một mô hình thì dùng trực tiếp công cụ chat là đủ. Cũng có bản hosted trên trang chủ dự án, nhưng đó là sản phẩm riêng, có gói trả phí và chính sách dữ liệu riêng; hãy đọc kỹ điều khoản của họ nếu cân nhắc. Còn nếu bạn thích thử nghiệm, muốn tự chủ dữ liệu và có sẵn một công cụ AI, Suparagent đáng thử trước với một thư mục nhỏ và chế độ Ask first.
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 desktop hoặc tự host bạn chạy được từ repo. Tuy nhiên Suparagent không kèm mô hình hay gói đăng ký AI, bạn tự mang tài khoản nhà cung cấp và trả phí dùng mô hình nếu có. Bản hosted trên trang chủ là sản phẩm riêng, có gói trả phí.
Cần GPU hay máy mạnh không?
Tư liệu không nêu yêu cầu phần cứng hay GPU. Suparagent chỉ điều phối, còn việc tính toán do engine bạn chọn đảm nhiệm. Nếu dùng engine chạy cục bộ như Ollama hay LM Studio thì cấu hình phụ thuộc mô hình đó, repo chưa có thông tin cụ thể.
Chạy được trên Windows không?
README mô tả chạy bản desktop từ mã nguồn với Node.js 22+, uv và một engine, không loại trừ hệ điều hành nào. Trong repo có file run-desktop.bat nhưng README không giải thích cách dùng. Bộ cài desktop được ghi là thử nghiệm, chưa ký số và mới kiểm chứng nền tảng hạn chế.
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 máy chủ của bạn, khoá API lưu qua Suparagent được mã hoá. Tuy nhiên mỗi lượt trả lời, engine bạn chọn nhận câu hỏi và ngữ cảnh cần thiết; 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.
Agent có tự làm bậy khi tôi không để ý không?
Bạn chọn mức tự do: Ask first, Accept edits, Approve for me (Claude, Codex, Cursor) hoặc Plan only. Routine không bao giờ tự duyệt hành động thay bạn, và các thay đổi qua ứng dụng kết nối cũng chờ bạn duyệt. Bạn xem lại hoạt động công cụ và quyết định duyệt trong app.
Cần tài khoản hay API key nào?
Cần ít nhất một engine: CLI như Claude Code hoặc Codex đã đăng nhập, hoặc API như OpenRouter, Ollama, LM Studio cấu hình trong Settings → Engines. Muốn nối GitHub, Gmail, Google Calendar thì cần khoá Composio của riêng bạn. Docker chỉ cần nếu dùng máy tính riêng cho agent.
Khác gì chat trực tiếp với một mô hình AI?
Suparagent thêm lớp tổ chức: agent có tên và công việc riêng, trí nhớ xem được và sửa được, đội nhiều agent, routine chạy theo lịch, bảng việc và luồng duyệt hành động. Nó không thay thế mô hình mà dùng engine bạn đã có. Repo chưa so sánh chi tiết với từng sản phẩm cụ thể ngoài phần mô tả.


