Suparagent: đồng nghiệp AI có tên, có trí nhớ, chạy trên máy bạn — 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 agent AI có tên, có vai trò, trí nhớ, lịch chạy và bước xin duyệt trước khi hành động. Bạn chạy bản desktop từ mã nguồn hoặc tự dựng máy chủ, rồi nối với engine AI bạn đã có. Cài không quá khó nhưng cần Node.js 22+, uv và một engine; dự án vẫn ở giai đoạn 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 nó một công việc và một thư mục làm việc, rồi cho nhiều agent phối hợp làm việc thật. Cuộc trò chuyện, trí nhớ, lịch chạy định kỳ và các lần xin duyệt đều nằm chung một chỗ. Bạn 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 một là người làm văn phòng, chủ shop muốn có «trợ lý» làm việc lặp lại như tổng hợp báo cáo hằng tuần. Nhóm hai là lập trình viên mới muốn thử mô hình nhiều agent mà không bị khoá vào một nhà cung cấp. Nhóm ba là người ngại giao quyền tự do cho AI, vì Suparagent có chế độ hỏi bạn trước khi agent làm gì đó.
Điểm đáng giá nhất là bạn mang engine của chính mình: Claude Code, Codex CLI, Gemini CLI, Cursor, OpenRouter hoặc API tương thích OpenAI như Ollama, LM Studio. Suparagent không kèm sẵn mô hình hay gói đăng ký nào. Hiện repo có khoảng 7.000 sao và 900 fork, và vẫn được cập nhật trong vài tháng gần đây. 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 các đồng nghiệp AI có tên, có trí nhớ, lịch chạy định kỳ và chỉ hành động khi bạn đồng ý.
I.Suparagent làm được gì
A.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à mức duyệt riêng. Bạn có thể đặt một agent «trưởng nhóm» chia việc cho các agent chuyên môn, ví dụ một người nghiên cứu và một người biên tập. Lợi ích thực tế là bạn không phải nhồi mọi thứ vào một cuộc chat dài: mỗi agent làm phần việc của nó, rồi trả kết quả về cho trưởng nhóm. Lưu ý: README nói agent trưởng nhóm hiện cần dùng Claude hoặc Codex.
B.Trí nhớ có thể xem và sửa
Agent có thể ghi chú, nhắc lại ghi chú liên quan và tìm trong lịch sử trò chuyện. Bạn xem và sửa được những gì nó nhớ. Nhờ vậy lần sau bạn không cần giải thích lại từ đầu, và nếu agent nhớ sai thì bạn sửa được.
C.Routine: chạy việc theo lịch
Routine chạy theo lịch, theo webhook hoặc bấm tay. Mỗi kết quả đều để bạn xem lại, và routine không bao giờ tự duyệt một hành động thay bạn. Một điều cần biết: routine chạy ở backend, nên backend phải đang chạy thì lịch mới hoạt động.
D.Chọn mức tự do cho agent
Có bốn chế độ: Ask first (hỏi trước khi làm), Accept edits (chấp nhận chỉnh sửa), Approve for me (chỉ có với Claude, Codex và Cursor) và Plan only (chỉ lập kế hoạch). Bạn xem lại được hoạt động công cụ và các quyết định duyệt trong ứng dụng. Với người mới, mình khuyên bắt đầu bằng Ask first.
E.Kết nối ứng dụng và 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 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ẻ.
F.Màn hình Today, bảng việc và lịch
Màn hình Today gom các thứ cần bạn để ý: 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ó thể hiện thư Gmail và lịch ở dạng chỉ đọc. Bảng việc và lịch giúp giao việc, hẹn chạy một lần và xem lại các lần làm.
G.Skill, mẫu agent, ứng dụng điện thoại và quản lý file
Bạn lưu skill (hướng dẫn dùng lại cho một tin nhắn) và tạo agent từ mẫu có sẵn. Có ứng dụng điện thoại ghép 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ệnh. Bạn cũng 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 sự đồng ý và thông tin xác thực của bạn), duyệt hoặc tải file trong workspace, và xuất lịch sử.
II.Cần chuẩn bị gì
Theo README, bản desktop chạy từ mã nguồn và cần:
- Node.js 22 trở lên.
- uv (công cụ quản lý Python, có trang hướng dẫn riêng của uv).
- Ít nhất một engine có sẵn trên cùng máy tính.
Về engine: nếu dùng engine dạng dòng lệnh (CLI), bạn phải cài và đăng nhập nó trước khi mở ứng dụng. Nếu muốn dùng engine qua API, bạn cấu hình trong Settings → Engines. Docker chỉ cần khi bạn muốn bật các «máy tính cô lập» cho agent, và phần này là tuỳ chọn.
Về chi phí: Suparagent miễn phí và mã nguồn mở, nhưng dùng mô hình có thể tốn tiền theo nhà cung cấp bạn chọn. README cũng nói rõ phần máy chủ tự host cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine. README không nêu yêu cầu về hệ điều hành cho bản desktop hay yêu cầu về phần cứng như GPU.
Suparagent không kèm mô hình AI. Khi agent trả lời, engine bạn chọn sẽ nhận câu lệnh và phần ngữ cảnh cần thiết, có thể gồm file bạn đính kèm, ghi chú liên quan và nội dung trong workspace 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. Hãy cẩn thận khi giao thư mục chứa thông tin nhạy cảm, và đừng chia sẻ khoá API cho ai.
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 engine nếu là CLI
- Tải mã nguồnDùng git clone để lấy repo về máy
- Chạy ứng dụngVào thư mục desktop và chạy npm run app
- Chọn 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, chọn thư mục làm việc rồi bắt đầu chat
A.Chuẩn bị Node.js, uv và engine
Trước khi gõ lệnh, hãy chắc chắn máy bạn đã có Node.js 22 trở lên và uv. README không ghi lệnh cài chúng, nên bạn xem hướng dẫn trên trang chính thức của từng công cụ. Nếu định dùng Claude Code hay Codex CLI làm engine, hãy cài và đăng nhập nó trước. Chỗ người mới hay vấp là quên đăng nhập engine, rồi vào ứng dụng thấy engine «chưa sẵn sàng».
B.Tải mã nguồn và chạy ứng dụng
Mở terminal (trên Windows là PowerShell hoặc Git Bash, trên macOS và Linux là Terminal) ở thư mục bạn muốn đặt dự án, rồi chạy đúng ba lệnh trong README:
git clone https://github.com/Anil-matcha/suparagent.git
cd suparagent/desktop
npm run appLệnh đầu tải mã nguồn về. Lệnh thứ hai đi vào thư mục desktop. Lệnh thứ ba khởi động ứng dụng. Bạn phải đứng trong thư mục suparagent/desktop khi chạy npm run app, nếu không lệnh sẽ báo lỗi không tìm thấy script. README không ghi thêm bước cài phụ thuộc nào khác, nên bạn cứ làm đúng như trên trước, và nếu terminal báo thiếu gì thì đọc kỹ thông báo đó.
C.Thiết lập lần đầu
Lần đầu mở, ứng dụng yêu cầu bạn chọn engine, workspace và chế độ duyệt. Sau đó README gợi ý làm theo thứ tự này:
- 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 rõ ràng và một workspace.
- 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.
- Thêm đồng đội hoặc tạo routine khi bạn muốn chia việc hay lặp lại việc.
Nếu muốn dùng engine qua API thay vì CLI, bạn khai báo trong Settings → Engines. Hãy điền khoá API ngay trong màn hình đó, đừng dán khoá vào ô chat.
D.Muốn bản cài sẵn hoặc tự dựng máy chủ
README có nhắc trang Releases với các bộ cài desktop, nhưng ghi rõ chúng thử nghiệm và chưa ký số. Luồng cập nhật có hỗ trợ kiểm tra SHA-256 nhưng không tự cài, và đường cập nhật giữa các bản chưa được kiểm chứng trọn vẹn. Với máy chủ tự host, repo có Dockerfile và compose.yaml, nhưng README chính chưa ghi lệnh cụ thể. Bạn xem hướng dẫn self-hosting trong thư mục docs/ của repo trước khi làm.
IV.Kiểm tra đã chạy được chưa
Dấu hiệu cài thành công theo README khá đơn giản:
- Sau
npm run app, ứng dụng mở lên và hiện màn hình thiết lập lần đầu để bạn chọn engine, workspace và chế độ duyệt. - Trong Settings → Engines, engine bạn dùng hiện ở trạng thái sẵn sàng.
- Bạn tạo được một agent và chat được; với Ask first, khi agent định làm việc cần duyệt thì ứng dụng dừng lại chờ bạn.
Cách thử nhanh: tạo một agent tên «Thử nghiệm», giao một thư mục trống làm workspace và nhắn «Hãy giới thiệu ngắn về công việc của bạn». Nếu có câu trả lời, engine đã nối được. Nếu không, nhiều khả năng engine chưa đăng nhập hoặc chưa cấu hình, chứ chưa chắc ứng dụng hỏng.
V.Dùng vào việc thật
A.Chủ shop: bản tin tuần từ báo cáo bán hàng
Bối cảnh: bạn có thư mục chứa ghi chú và báo cáo bán hàng mỗi tuần, và mỗi thứ Hai phải ngồi tổng hợp. Làm theo ví dụ trong README: 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 người biên tập. Cho cả ba cùng một workspace và đặt engine của trưởng nhóm là Claude hoặc Codex. Sau đó nhắn:
Hãy soạn bản tổng hợp tuần này từ các ghi chú và báo cáo trong thư mục, chia việc cho người nghiên cứu và người biên tập.Trưởng nhóm chia việc thành các phần nhỏ, giao cho đồng đội làm trong các cuộc trò chuyện riêng, rồi gom lại. Bạn theo dõi trong chat và duyệt khi cài đặt yêu cầu. Kết quả là một bản tổng hợp để bạn đọc, sửa và dùng.
Khi quy trình đã chạy tốt, hãy biến nó thành routine hằng tuần và chỉ việc duyệt kết quả.
Ông T
B.Nhân viên văn phòng: biến việc lặp lại thành routine
Bối cảnh: tuần nào bạn cũng làm một việc giống nhau, ví dụ soạn bản nháp báo cáo. Sau khi thử tay vài lần ổn, vào phần routine, chọn chạy theo lịch hoặc theo webhook, hoặc để chạy bấm tay. Mỗi lần chạy ra kết quả, bạn xem lại và trả lời các yêu cầu duyệt. Nhớ là routine không tự duyệt thay bạn, và backend phải luôn chạy thì lịch mới hoạt động, nên máy cần bật.
C.Người hay bận: theo dõi việc bằng Today và điện thoại
Bối cảnh: bạn không muốn mở từng cuộc chat để biết agent nào đang chờ mình. Mở màn hình Today để thấy 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 đã tự host máy chủ, bạn ghép ứng dụng điện thoại để cho phép hoặc từ chối một lệnh ngay trên máy. README lưu ý ứng dụng điện thoại mới thử trên Android, chưa có iOS, chưa có thông báo đẩy.
D.Lập trình viên: thử engine và công cụ khác nhau
Bối cảnh: bạn muốn so sánh vài engine cho cùng một việc. Tạo vài agent, mỗi agent dùng một engine khác (Claude Code, Gemini CLI hoặc Ollama qua API tương thích OpenAI) với cùng workspace, rồi giao cùng một yêu cầu. Bạn cũng có thể nối GitHub qua khoá Composio của mình và cấp cho agent Claude hoặc Codex được chọn; mọi thay đổi vẫn chờ bạn duyệt. README nói phần này mới thử với một dịch vụ Composio giả lập, chưa phải dịch vụ thật, nên hãy dùng thận trọng.
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à chưa đăng nhập engine CLI, hoặc chưa cấu hình khoá API. Hãy đăng nhập engine ngoài terminal trước, rồi vào Settings → Engines kiểm tra lại. Nếu dùng API, kiểm tra khoá đã điền đúng chỗ chưa.
B.Lỗi khi chạy npm run app
Hai nguyên nhân dễ xảy ra: đứng sai thư mục (phải là suparagent/desktop) hoặc phiên bản Node.js cũ hơn 22. Chạy node --version để xem phiên bản. Nếu thiếu uv, cài uv theo hướng dẫn trên trang của nó. Nếu vẫn lỗi, đọc thông báo trong terminal và hỏi ở GitHub Issues hoặc Discord của dự án.
C.Routine không chạy theo lịch
Routine chạy ở backend, nên nếu ứng dụng hay máy chủ đã tắt thì lịch không chạy. Hãy để backend chạy liên tục, hoặc dựng trên máy chủ bạn luôn bật.
D.Agent trưởng nhóm không chia được việc
Tính năng giao việc theo nhóm còn mới và README ghi rõ agent trưởng nhóm phải dùng Claude hoặc Codex. Nếu bạn đặt engine khác cho trưởng nhóm, hãy đổi lại.
E.Tính năng Docker, trình duyệt hoặc cài đặt bộ cài gặp trục trặc
Máy tính Docker, công cụ trình duyệt và bản desktop native cho macOS là thử nghiệm và phải bật tay. Bộ cài desktop chưa ký số nên hệ điều hành có thể cảnh báo. Cách an toàn là chạy từ mã nguồn như phần cài đặt ở trên, còn việc quan trọng thì đừng chỉ dựa vào các tính năng thử nghiệm này.
VII.Có nên dùng không
Điểm mạnh: bạn giữ quyền kiểm soát. Dữ liệu hội thoại, ghi chú, routine và cài đặt nằm trên máy hoặc máy chủ của bạn, khoá API lưu trong Suparagent được mã hoá, và mọi hành động quan trọng đều có thể chờ bạn duyệt. Bạn không bị khoá vào một nhà cung cấp mô hình, và giấy phép Apache-2.0 khá thoải mái.
Giới hạn: dự án đang phát triển nhanh và README tự nhận nhiều phần còn thử nghiệm. Máy chủ tự host chỉ có một chủ sở hữu mời được đồng đội, và mọi người dùng chung agent, hội thoại, trí nhớ; nó không phải dịch vụ nhiều tổ chức. Phần kết nối ứng dụng, MCP Marketplace, máy tính đám mây và chuyển âm thanh thành chữ chưa được kiểm chứng đầy đủ. Ngoài ra bạn vẫn tự trả tiền cho nhà cung cấp mô hình, và README không có thông tin về hiệu năng trên từng loại máy.
Nên dùng nếu bạn muốn thử mô hình «đồng nghiệp AI» có kiểm soát và không ngại cấu hình. Nên chọn cách khác nếu bạn cần thứ ổn định tuyệt đối cho việc sống còn, hoặc không muốn đụng đến terminal và engine. Khi đó, một dịch vụ trò chuyện AI có sẵn có thể hợp hơn. Cũng có bản web riêng do Suparagent vận hành với gói trả phí, nhưng đó là sản phẩm tách biệt với bản mã nguồn mở trong bài này.
Câu hỏi thường gặp
Suparagent có miễn phí không?
Phần mã nguồn mở (desktop và tự host) dùng giấy phép Apache-2.0 và miễn phí. Tuy nhiên Suparagent không kèm mô hình AI, nên bạn vẫn có thể phải trả tiền cho nhà cung cấp engine mình dùng. Bản web do Suparagent vận hành là sản phẩm riêng, có gói miễn phí để dùng thử và các gói trả phí.
Có cần GPU không?
README không nói về yêu cầu GPU hay cấu hình phần cứng cho Suparagent. Vì ứng dụng dùng engine bạn đã có, như Claude Code, Codex hay API, nhu cầu phần cứng phụ thuộc vào engine bạn chọn. Nếu muốn chạy mô hình nội bộ, README chỉ nhắc đến Ollama và LM Studio qua API tương thích OpenAI.
Chạy được trên Windows không?
Repo có tệp run-desktop.bat, nhưng README không nêu rõ danh sách hệ điều hành được hỗ trợ cho bản desktop. README chỉ nói bộ cài desktop là thử nghiệm, chưa ký số và mới được kiểm chứng trên số nền tảng hạn chế. Bạn nên thử và xem Issues nếu gặp lỗi.
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, và khoá API lưu qua Suparagent được mã hoá. Như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; nếu là dịch vụ đám mây thì theo điều khoản của họ. Bản web hosted thì dữ liệu do Suparagent xử lý theo chính sách riêng.
Cần những gì để cài bản desktop?
Bạn cần Node.js 22 trở lên, uv và ít nhất một engine trên cùng máy. Docker chỉ cần nếu muốn dùng máy tính cô lập cho agent. Các bước là git clone repo, vào thư mục desktop rồi chạy npm run app.
Khác gì chỉ chat với Claude hay ChatGPT?
Suparagent là lớp quản lý nhiều agent có tên, trí nhớ, routine, bảng việc và bước duyệt, chạy trên engine bạn chọn. README mô tả nó là phương án mã nguồn mở, tự host thay cho một số công cụ agent khác, nhưng không đưa ra so sánh chi tiết từng tính năng. Vì vậy nếu bạn chỉ cần hỏi đáp đơn giản thì chat thông thường là đủ.
Dự án đã ổn định chưa?
Chưa hoàn toàn. README ghi dự án đang phát triển, bản tự host và bộ cài desktop là thử nghiệm, và nhiều tính năng như kết nối ứng dụng, MCP Marketplace, máy tính Docker còn chưa được kiểm chứng đầy đủ. Hãy xem mục hạn chế đã biết trong README trước khi dùng cho việc quan trọng.


