Suparagent: đồng nghiệp AI có tên, có trí nhớ, chờ bạn 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 "đồng nghiệp AI" có tên, vai trò, trí nhớ và lịch chạy riêng, chạy trên máy hoặc server của bạn. Bạn tự mang engine AI của mình (Claude Code, Codex, Gemini CLI, Ollama…) vì repo không kèm mô hình. Bản desktop chạy từ mã nguồn bằng ba lệnh, cần Node.js 22+ và uv; README ghi rõ đây là bản thử nghiệm.
Suparagent là một không gian làm việc cho các "đồng nghiệp AI". Bạn tạo ra những agent có tên riêng, giao cho mỗi agent một nhiệm vụ và một thư mục làm việc, rồi cho chúng cùng xử lý công việc thật. Cuộc trò chuyện, trí nhớ, lịch chạy định kỳ và các yêu cầu duyệt đều nằm chung một chỗ. Repo là mã nguồn mở, giấy phép Apache-2.0, viết chủ yếu bằng Python, hiện có khoảng 7.041 sao và 913 fork.
Ai nên dùng? Người làm văn phòng, chủ shop nhỏ hoặc lập trình viên đã quen dùng Claude Code, Codex hay một công cụ AI dòng lệnh khác, và muốn có chỗ quản lý nhiều "trợ lý" thay vì mở từng cửa sổ chat rời rạc. Điểm đáng giá nhất là cơ chế duyệt: bạn chọn mức tự do cho agent, và routine (công việc chạy định kỳ) không bao giờ tự duyệt thay bạn. Dữ liệu của bản desktop và bản tự host nằm trên máy hoặc server của bạn.
Một lưu ý trước khi bắt đầu: Suparagent không kèm mô hình AI hay gói thuê bao nào. Bạn phải mang theo engine và tài khoản của riêng mình. Tác giả cũng ghi dự án đang phát triển tích cực, nhiều phần còn thử nghiệm. 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
Suparagent là không gian làm việc mã nguồn mở cho đồng nghiệp AI: có tên, nhiệm vụ, trí nhớ, lịch chạy định kỳ và luôn 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 agent. 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. Bạn có thể đặt một agent làm "trưởng nhóm" để giao việc cho các chuyên viên (ví dụ một người nghiên cứu, một người biên tập). Trưởng nhóm hiện phải dùng Claude hoặc Codex.
- Giữ ngữ cảnh lâu dài. Agent 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ớ, nên không sợ "nhớ sai" mà không biết.
- Chạy việc theo lịch. Routine chạy theo lịch, qua webhook hoặc bấm tay. Mỗi kết quả bạn đều xem lại được, và mọi yêu cầu duyệt vẫn đợi bạn trả lời.
- Chọn mức tự do cho agent. Có bốn chế độ: Ask first (hỏi trước), Accept edits (tự nhận chỉnh sửa), Approve for me (dành cho Claude, Codex và Cursor) và Plan only (chỉ lập kế hoạch). Hoạt động công cụ và quyết định duyệt đều xem lại được trong app.
- Nối công cụ và ứng dụng. Bạn nối GitHub, Gmail, Google Calendar… qua khoá Composio của chính bạn, rồi cấp quyền cho từng agent Claude hoặc Codex được chọn. Các thay đổi vẫn chờ bạn duyệt. Ngoài ra có MCP Marketplace để thêm từng công cụ riêng lẻ.
- Màn hình Today. Gom lại 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 thư 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 các cuộc trò chuyện và lần thử.
- Kỹ năng (skills) và mẫu agent. Lưu sẵn các chỉ dẫn hay dùng để gắn vào tin nhắn, và tạo agent mới từ mẫu cho nhanh.
- 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 công cụ. README ghi app này mới thử trên Android, chưa có iOS, chưa có thông báo đẩy.
- 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ử.
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 (công cụ quản lý Python do trang docs.astral.sh/uv hướng dẫn cài).
- Ít nhất một engine có sẵn trên cùng máy. Danh sách engine README nêu: Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, một công cụ dòng lệnh khác dùng giao thức Agent Client Protocol (ACP), OpenRouter, hoặc API tương thích OpenAI như Ollama và LM Studio.
- Nếu dùng engine dòng lệnh: cài nó và đăng nhập xong trước khi mở Suparagent. Nếu dùng engine qua API: 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 (tính năng tuỳ chọn, còn thử nghiệm).
- Tài khoản và khoá của nhà cung cấp AI mà bạn chọn. Chi phí dùng mô hình do nhà cung cấp đó tính.
Tư liệu không nói rõ yêu cầu về phần cứng hay hệ điều hành cho bản desktop. Với bản tự host trên server, README ghi cần máy chủ Linux, HTTPS, Docker (hoặc Node.js và uv) và một engine. Repo có kèm file run-desktop.bat, nhưng README không giải thích cách dùng nó, nên mình không khuyên bạn đoán mò.
Suparagent chỉ là "bộ điều phối". Prompt và nội dung cần thiết cho mỗi lượt (văn bản bạn đính kèm, ghi chú liên quan, nội dung tệp mà engine đọc) sẽ được gửi tới engine bạn chọn. Nếu engine là dịch vụ trên mạng, dữ liệu đó thuộc điều khoản của nhà cung cấp. Đừng giao tệp nhạy cảm cho agent nếu bạn chưa yên tâm về engine.
III.Cài đặt từng bước
- Chuẩn bị công cụCài Node.js 22+, uv và ít nhất một engine AI đã đăng nhập
- Tải mã nguồnDùng git clone để kéo repo về máy
- Chạy ứng dụngVào thư mục desktop và chạy npm run app
- Thiết lập lần đầuChọn engine, thư mục làm việc và chế độ duyệt
- Tạo agent đầu tiênĐặt tên, giao việc, mở chat với chế độ Ask first
A.Chuẩn bị Node.js, uv và engine
README không ghi lệnh cài Node.js hay uv, nên bạn cài theo trang chủ của từng công cụ. Sau đó hãy kiểm tra phiên bản Node, vì yêu cầu là 22 trở lên:
node --versionLệnh này in ra số phiên bản Node đang có. Nếu thấy số nhỏ hơn 22, bạn cần nâng cấp trước. Với engine, ví dụ bạn dùng Claude Code hay Codex, hãy cài và đăng nhập nó trong terminal trước. Đây là chỗ người mới hay quên: Suparagent không tự đăng nhập hộ engine dòng lệnh.
B.Tải mã nguồn về máy
Mở terminal (trên Windows là PowerShell hoặc Git Bash, nơi bạn đã cài Git) tại 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.Chạy ứng dụng desktop
Vào thư mục desktop và chạy ứng dụng, đúng như README:
cd suparagent/desktop
npm run appLệnh cd đưa terminal vào thư mục desktop. Lệnh npm run app mở ứng dụng. Phải đứng trong thư mục desktop thì lệnh mới chạy; nếu báo không tìm thấy script, kiểm tra lại bạn đang ở đâu. README không ghi thêm bước cài phụ thuộc nào khác. Nếu máy báo thiếu gói, hãy xem phần hướng dẫn thiết lập desktop trong thư mục docs/ của repo.
README cũng nhắc có bản cài đặt (installer) trên trang Releases của repo, nhưng ghi rõ chúng còn thử nghiệm và chưa được ký số, nên Windows có thể cảnh báo khi mở.
D.Thiết lập lần đầu và tạo agent
Khi mở lần đầu, app yêu cầu chọn engine, thư mục làm việc và chế độ duyệt. Sau đó làm theo 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: đặt tên, viết rõ nhiệm vụ, chọn thư mục làm việc.
- Bắt đầu chat. Chọn Ask first để app dừng lại xin 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.
Lời khuyên cho người mới: hãy chọn Ask first trong vài ngày đầu. Bạn sẽ thấy agent định làm gì trước khi nó làm.
IV.Kiểm tra đã chạy được chưa
Tư liệu không mô tả một lệnh kiểm tra riêng. Cách kiểm tra thực tế theo các bước README là:
- Cửa sổ ứng dụng mở ra và hiện màn hình thiết lập lần đầu (chọn engine, workspace, chế độ duyệt).
- Trong Settings → Engines, engine bạn định dùng được báo là sẵn sàng.
- Bạn tạo được một agent và gửi tin nhắn đầu tiên, agent trả lời.
- Với chế độ Ask first, khi agent định làm một việc cần quyền (ví dụ sửa tệp), app hiện yêu cầu chờ bạn cho phép hoặc từ chối.
Nếu đến bước agent trả lời mà vẫn được, nghĩa là cả ứng dụng lẫn engine đã thông. Nếu engine báo lỗi, màn hình Today sẽ gom các lỗi engine để bạn xem.
V.Dùng vào việc thật
A.Chủ shop nhỏ: tóm tắt báo cáo hằng tuần
Bạn có thư mục chứa các file báo cáo bán hàng và ghi chú họp mỗi tuần. Tạo một agent tên "Trợ lý báo cáo", giao thư mục đó làm workspace, chọn Ask first. Gõ một câu lệnh mẫu như:
Đọc các ghi chú và báo cáo trong thư mục này, rồi viết bản tóm tắt tuần: việc đã xong, việc đang kẹt, 3 việc nên làm tuần sau.Kết quả là một bản tóm tắt ngay trong chat. Khi agent muốn ghi ra tệp mới, app sẽ hỏi bạn trước. Việc hợp với cách dùng này, README cũng có ví dụ tương tự là soạn briefing dự án hằng tuần.
Agent làm việc cho bạn, nhưng không bao giờ tự quyết thay bạn.
Ông T
B.Nhân viên văn phòng: một nhóm nhỏ nghiên cứu và biên tập
Tạo ba agent cùng dùng một thư mục dự án: một trưởng nhóm (đặt engine là Claude hoặc Codex, vì trưởng nhóm cần một trong hai), một người nghiên cứu và một người biên tập. Yêu cầu trưởng nhóm: "Soạn bản briefing từ các ghi chú trong thư mục". Trưởng nhóm tách việc, giao cho từng chuyên viên; mỗi người làm trong cuộc trò chuyện riêng rồi trả kết quả 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. Khi quy trình đã ổn, biến nó thành routine chạy hằng tuần.
C.Người hay quên việc: màn hình Today và routine
Bạn đặt một routine chạy mỗi sáng thứ Hai theo lịch, ví dụ "liệt kê các việc đến hạn trong tuần". Routine chạy ở backend, nên backend phải đang chạy thì lịch mới hoạt động; nếu bạn tắt máy, routine sẽ không chạy. Mở màn hình Today để thấy kết quả routine, câu hỏi từ agent và các yêu cầu duyệt đang chờ. Nếu bạn nối Gmail và Google Calendar qua Composio, Today có thể hiện thêm thư và lịch ở chế độ chỉ đọc.
D.Lập trình viên: nhiều engine, một chỗ quản lý
Nếu bạn đã dùng Claude Code cho dự án này, Codex cho dự án kia, hoặc chạy mô hình cục bộ qua Ollama hay LM Studio, Suparagent cho phép mỗi agent dùng một engine khác nhau mà vẫn quản lý trong cùng ứng dụng. Bạn dùng Plan only để agent chỉ lập kế hoạch, hoặc Accept edits khi tin tưởng. Muốn dùng trên server riêng, đọc hướng dẫn self-hosting trong docs/; repo có sẵn Dockerfile và compose.yaml, nhưng README chưa nêu lệnh cụ thể nên bạn cần làm theo tài liệu đó.
VI.Lỗi hay gặp và cách xử lý
A.Engine báo chưa sẵn sàng
Thường do engine dòng lệnh chưa được cài hoặc chưa đăng nhập. Mở terminal, chạy engine một mình, đăng nhập xong rồi quay lại Settings → Engines. Với engine API, kiểm tra lại khoá và địa chỉ đã điền đúng chưa.
B.Lệnh npm run app báo lỗi hoặc không tìm thấy
Kiểm tra bạn đang đứng trong thư mục suparagent/desktop, không phải thư mục gốc. Kiểm tra node --version đã từ 22 trở lên và uv đã cài. README chưa liệt kê thêm bước cài phụ thuộc, nên nếu lỗi nói thiếu gói, xem phần desktop setup trong docs/ hoặc hỏi ở GitHub Issues của repo.
C.Windows cảnh báo khi mở bản installer
Tác giả ghi bản cài đặt chưa được ký số và còn thử nghiệm, nên cảnh báo là bình thường. Nếu bạn không yên tâm, hãy chạy từ mã nguồn bằng các lệnh ở trên, hoặc chỉ tải installer từ trang Releases chính thức của repo.
D.Routine không chạy đúng giờ
Routine chạy ở backend, nên nếu backend đã tắt (máy ngủ, tắt ứng dụng) thì lịch bị bỏ lỡ. Hãy giữ backend chạy, hoặc đưa lên server nếu cần chạy liên tục. Một routine cũng không tự duyệt hành động; nếu thấy nó "đứng", mở Today xem có yêu cầu duyệt đang chờ không.
E.Tính năng nối ứng dụng, máy tính Docker hoặc chợ MCP hoạt động lạ
README thừa nhận các phần này còn thử nghiệm: kết nối ứng dụng mới được thử với một dịch vụ Composio giả lập, chưa thử với dịch vụ thật; Docker computers và công cụ trình duyệt là tuỳ chọn thử nghiệm. Hãy thử với dữ liệu không quan trọng trước, và chỉ cấp quyền cho agent thật sự cần.
VII.Có nên dùng không
Điểm mạnh. Bạn tự giữ dữ liệu trên máy hoặc server của mình, tự chọn engine, và có nhiều mức duyệt rõ ràng. Một chỗ gom trí nhớ, lịch chạy, nhóm agent và việc cần bạn chú ý khá tiện nếu bạn đang dùng nhiều trợ lý AI. Giấy phép Apache-2.0 cho phép dùng và chỉnh sửa tự do, và repo vẫn được cập nhật trong những tháng gần đây.
Giới hạn. Đây là phần mềm còn sớm. README tự ghi: server tự host là thử nghiệm, chỉ có một chủ sở hữu (có thể mời đồng đội), không phải dịch vụ nhiều tổ chức; giao việc theo nhóm còn mới; app điện thoại chưa có iOS; nhiều tính năng chưa được kiểm thử trên dịch vụ thật. Bạn vẫn phải tự lo engine, tài khoản và chi phí mô hình. Cài từ mã nguồn bằng Node và uv cũng không hẳn dễ với người chưa từng mở terminal.
Khi nào chọn cách khác. Nếu bạn chỉ cần hỏi đáp thỉnh thoảng, một ứng dụng chat thông thường đơn giản hơn. Nếu cần dịch vụ ổn định cho cả công ty và có hỗ trợ, bạn có thể xem bản hosted trên trang chủ của dự án, nhưng đó là sản phẩm riêng, có gói trả phí và chính sách riêng, không thuộc phần mã nguồn mở. Nếu việc của bạn quan trọng và không chấp nhận rủi ro, hãy thử trên dữ liệu phụ trước rồi mới mở rộ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 dùng bản desktop hoặc tự host mà không phải trả phí cho Suparagent. Tuy nhiên README ghi repo không kèm mô hình hay gói thuê bao, nên bạn vẫn phải trả cho nhà cung cấp AI nếu engine của bạn tính phí. Bản hosted trên trang chủ là sản phẩm riêng với các gói trả phí.
Có cần GPU không?
Tư liệu không nêu yêu cầu GPU hay phần cứng cho bản desktop. Mô hình chạy ở engine bạn chọn (CLI, API hoặc Ollama/LM Studio), nên nhu cầu phần cứng phụ thuộc vào engine đó.
Chạy được trên Windows không?
README không liệt kê hệ điều hành cho bản desktop, chỉ ghi cần Node.js 22+, uv và một engine. Trong repo có file run-desktop.bat, nhưng README chưa giải thích cách dùng. Bản cài đặt được ghi là thử nghiệm, chưa ký số và kiểm chứng nền tảng còn hạn chế. Bản self-host thì cần máy chủ Linux.
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ú agent, routine và cài đặt lưu ở thư mục dữ liệu trên máy hoặc database trên server của bạn; khoá API lưu qua Suparagent được mã hoá. Nhưng engine bạn chọn sẽ nhận prompt và ngữ cảnh cần cho mỗi lượt, và nếu là dịch vụ trên mạng thì áp dụng điều khoản của nhà cung cấp đó.
Agent có tự làm việc mà không hỏi tôi không?
Bạn chọn mức tự do: Ask first, Accept edits, Approve for me (cho Claude, Codex, Cursor) hoặc Plan only. Riêng routine thì README khẳng định nó không bao giờ tự duyệt một hành động; mọi yêu cầu duyệt vẫn chờ bạn trả lời.
Dùng được engine nào?
README liệt kê Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, công cụ dòng lệnh dùng giao thức ACP, OpenRouter và API tương thích OpenAI như Ollama hoặc LM Studio. Khả năng của từng engine khác nhau, ví dụ không phải engine nào cũng hỗ trợ ảnh hay máy tính cô lập.
Tôi dùng được trên điện thoại không?
Có 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 lệnh công cụ, tạo và sửa agent. README ghi mới thử trên Android (máy ảo và một điện thoại thật), chưa thử trên iOS, chưa có thông báo đẩy hay bản trên kho ứng dụng.


