Bỏ qua tới nội dung
Ông T.vn

Suparagent: đồng nghiệp AI có tên, có bộ nhớ, chờ bạn duyệt — hướng dẫn cài đặt và dùng

11 phút đọcCập nhật

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 →

Suparagent: đồng nghiệp AI có tên, có bộ nhớ, chờ bạn duyệt — 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: mỗi agent có tên, nhiệm vụ, thư mục làm việc, bộ nhớ và chế độ phê duyệt. Bạn chạy bản desktop hoặc tự dựng server, 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+, uv và một engine; README ghi dự án còn ở giai đoạ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 agent có tên, giao việc, cho thư mục làm việc riêng, rồi để chúng phối hợp làm việc thật. Hội thoại, bộ nhớ, lịch chạy định kỳ và các yêu cầu phê duyệt đều nằm chung một chỗ. Bạn chạy bản desktop trên máy mình hoặc tự dựng server riêng.

Repo này hợp với người muốn có “nhân viên AI” nhưng không muốn mất quyền kiểm soát: chủ shop cần ai đó tổng hợp báo cáo mỗi tuần, nhân viên văn phòng cần trợ lý đọc ghi chú và soạn bản tóm tắt, lập trình viên mới muốn thử mô hình nhiều agent. Đ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, và lịch chạy tự động cũng không bao giờ tự duyệt thay bạn.

Một điều cần nói trước: Suparagent không kèm 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. Hiện repo có khoảng 7.041 sao và 913 fork, nhưng tác giả ghi rõ dự án đang phát triển nhanh và nhiều phần còn ở mức thử nghiệm. Xem video ngắn bên dưới để thấy giao diện trước khi cài.

Ứng dụng

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ó bộ nhớ, chạy theo lịch và luôn hỏi bạn duyệt trước khi hành động.

★ 7kPythonApache-2.0
Xem repo trên GitHub
Video giới thiệu suparagentXem trên YouTubeXem trên Facebook

I.Suparagent làm được gì

Dưới đây là những tính năng chính, theo cách dễ hiểu.

  • Tạo agent và nhóm agent. Mỗi agent có tên, vai trò, engine, thư mục làm việc, bộ nhớ và mức phê 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 họ trong phòng chung. README lưu ý trưởng nhóm cần dùng Claude hoặc Codex.
  • Bộ nhớ có thể xem và sửa. Agent lưu ghi chú, nhớ lại ghi chú và hội thoại liên quan, tìm trong lịch sử. Bạn xem và chỉnh được những gì chúng nhớ, nên không sợ agent “nhớ sai” mà không biết.
  • Routine (việc chạy theo lịch). Một việc có thể chạy theo lịch, qua webhook, hoặc chạy tay. Bạn xem từng kết quả và trả lời các yêu cầu phê duyệt. Routine không tự duyệt hành động nào.
  • Chọn mức tự do cho agent. Có các chế độ Ask first (hỏi trước), Accept edits (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 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ụ.
  • 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ó thể hiện thêm email 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 hội thoại và các lần thử.
  • Skill và template. Lưu sẵn hướng dẫn để dùng lại, tạo agent mới từ mẫu có sẵn.
  • 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.
  • 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 để phiên âm (khi 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 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 trên cùng máy. Engine có thể là Claude Code hoặc Codex CLI, Gemini CLI, Gemini qua Antigravity, Cursor, một agent dòng lệnh dùng giao thức ACP, OpenRouter, hoặc API tương thích OpenAI như Ollama hay LM Studio.
  • Tài khoản nhà cung cấp AI. Nếu dùng engine dạng CLI, bạn cài và đăng nhập engine đó trước khi mở app. Nếu dùng engine dạng 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, và phần này là tuỳ chọn.

Về hệ điều hành, README chưa nêu rõ danh sách hệ điều hành cho bản desktop. Trong repo có file run-desktop.bat, gợi ý có hỗ trợ Windows, nhưng bạn nên xem thêm hướng dẫn cài desktop trong thư mục docs/ để chắc chắn. Về phần cứng, tư liệu cũng không nêu yêu cầu cụ thể.

Suparagent không đi kèm mô hình AI. Dùng engine trả phí thì bạn trả tiền cho nhà cung cấp đó. Khi agent trả lời, engine nhận lời nhắc và phần ngữ cảnh cần cho lượt đó, có thể gồm văn bản bạn đính kèm, ghi chú liên quan và nội dung tệp mà engine đọc. Đừng cho agent đọc thư mục chứa dữ liệu nhạy cảm nếu bạn chưa yên tâm về nhà cung cấp.

III.Cài đặt từng bước

  1. Chuẩn bị công cụ nềnCài Node.js 22+, uv và một engine (đã đăng nhập)
  2. Tải mã nguồnDùng git clone để lấy repo về máy
  3. Chạy ứng dụngVào thư mục desktop và chạy npm run app
  4. Chọn engine và thư mụcLần đầu mở app, chọn engine, workspace, chế độ duyệt
  5. Tạo agent đầu tiênĐặt tên, giao việc rõ ràng, bắt đầu chat

A.Chuẩn bị công cụ nền

Cài Node.js bản 22 trở lên và uv theo hướng dẫn trên trang của từng công cụ. Sau đó cài một engine. Nếu bạn dùng Claude Code hay Codex CLI, hãy đăng nhập xong rồi mới mở Suparagent, vì app dùng lại phiên đăng nhập có sẵn trên máy. README không kèm lệnh cài các công cụ này, nên bạn làm theo trang chủ của từng công cụ.

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 lưu dự án, rồi chạy:

Terminal
git clone https://github.com/Anil-matcha/suparagent.git

Lệnh này tạo thư mục suparagent chứa toàn bộ mã nguồn. Máy cần có Git; nếu báo không tìm thấy lệnh git, hãy cài Git trước.

C.Chạy ứng dụng

Vào thư mục desktop rồi chạy app, đúng như README:

Terminal
cd suparagent/desktop
npm run app

Lần chạy đầu có thể mất thời gian. Hãy giữ cửa sổ terminal mở trong lúc dùng app. README chỉ ghi hai lệnh này, không có bước cài thêm nào khác, nên mình không thêm gì vào.

D.Chọn engine, workspace và chế độ duyệt

Lần đầu mở app, bạn chọn engine, thư mục làm việc (workspace) và chế độ phê duyệt. Sau đó:

  1. Vào Settings → Engines và kiểm tra có engine nào ở trạng thái sẵn sàng.
  2. Tạo agent với tên, nhiệm vụ rõ ràng và thư mục làm việc.
  3. Bắt đầu chat. Chọn Ask first để app dừng lại hỏi bạn trước các hành động cần duyệt.
  4. Khi cần, thêm đồng đội cho agent hoặc tạo routine để lặp lại công việc.

Người mới nên bắt đầu với Ask first. Chế độ này chậm hơn một chút nhưng bạn thấy rõ agent định làm gì.

E.Cách khác: tự dựng server hoặc dùng bản cài sẵn

README còn nói tới server tự host (cần máy chủ Linux, HTTPS, Docker hoặc Node.js và uv, cùng một engine) và các bộ cài desktop trên trang Releases. Repo có Dockerfile và compose.yaml, nhưng README chưa ghi lệnh cụ thể, nên mình không chép lệnh nào ở đây. Bạn xem hướng dẫn self-hosting trong thư mục docs/ của repo. Các bộ cài desktop là bản thử nghiệm và chưa được ký số, nên Windows hay macOS có thể cảnh báo khi mở.

IV.Kiểm tra đã chạy được chưa

Theo README, bạn biết cài thành công khi cửa sổ app mở ra và hiện màn hình thiết lập lần đầu (chọn engine, workspace, chế độ duyệt). Kiểm tra tiếp ba điểm sau:

  • Trong Settings → Engines, engine bạn chọn hiện là sẵn sàng.
  • Bạn tạo được một agent có tên và thư mục làm việc.
  • Bạn gửi một tin nhắn ngắn, ví dụ “Liệt kê các tệp trong thư mục làm việc”, và nhận được trả lời. Với Ask first, nếu agent cần đọc hoặc sửa thứ gì, app sẽ hiện yêu cầu duyệt cho bạn.

Nếu engine không sẵn sàng, quay lại kiểm tra bạn đã đăng nhập CLI hay đã nhập đúng thông tin API chưa.

V.Dùng vào việc thật

A.Tổng hợp báo cáo dự án hằng tuần

Bối cảnh: bạn quản lý một dự án nhỏ, ghi chú và báo cáo nằm rải rác trong một thư mục. Cuối tuần nào bạn cũng mất cả buổi để gom lại.

Cách làm theo ví dụ trong README: tạo một agent trưởng nhóm và hai agent chuyên môn, như người nghiên cứu và người biên tập. Cho cả ba cùng thư mục dự án, và đặt engine của trưởng nhóm là Claude hoặc Codex. Rồi ra lệnh:

text
Hãy lập 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. Chia việc cho người nghiên cứu và người biên tập, rồi tổng hợp lại cho mình.

Kết quả: trưởng nhóm chia việc thành các phần nhỏ, mỗi chuyên gia làm trong hội thoại riêng rồi trả về để trưởng nhóm ghép lại. Bạn theo dõi trong chat và duyệt hành động khi cài đặt yêu cầu.

Cứ để agent làm nháp, còn quyết định cuối cùng vẫn là của bạn.

Ông T

B.Biến việc lặp lại thành routine

Bối cảnh: sau khi quy trình báo cáo ở trên chạy ổn, bạn không muốn ngồi nhắc lại mỗi tuần.

Cách làm: tạo một routine với đúng lời nhắc đó, chọn chạy theo lịch (hoặc webhook, hoặc chạy tay khi cần). Lưu ý README nói routine chạy ở backend, nên backend phải luôn chạy. Kết quả mỗi lần chạy hiện trong app để bạn xem; nếu cần phê duyệt, yêu cầu sẽ chờ bạn trả lời, routine không tự duyệt.

C.Chủ shop theo dõi việc cần xử lý trong ngày

Bối cảnh: bạn bán hàng và hay quên email hay lịch hẹn quan trọng.

Cách làm: nối Gmail và Google Calendar qua khoá Composio của bạn, cấp quyền cho một agent Claude hoặc Codex, rồi mở màn hình Today. Nơi này gom phê duyệt, câu hỏi, kết quả routine và việc đến hạn, kèm email và lịch ở chế độ chỉ đọc. Kết quả: mỗi sáng bạn có một chỗ duy nhất để xem hôm nay cần làm gì. README cũng cảnh báo phần kết nối ứng dụng mới được thử với dịch vụ Composio giả lập, chưa thử với dịch vụ thật, nên hãy dùng thận trọng.

D.Lập trình viên dùng agent với mô hình chạy trên máy

Bối cảnh: bạn không muốn gửi mã sang dịch vụ đám mây.

Cách làm: trong Settings → Engines, cấu hình một API tương thích OpenAI như Ollama hoặc LM Studio chạy trên máy. Tạo agent trỏ vào thư mục dự án, đặt chế độ Plan only để agent chỉ lập kế hoạch, hoặc Ask first để duyệt từng thay đổi. Kết quả: bạn có trợ lý đọc mã và đề xuất việc, còn dữ liệu đi đâu tuỳ vào engine bạn chọn. Lưu ý README nói công cụ khả dụng khác nhau giữa các engine, ví dụ không phải engine nào cũng nhận ảnh hay dùng được máy tính của agent.

VI.Lỗi hay gặp và cách xử lý

Engine không hiện là sẵn sàng. Thường do chưa cài hoặc chưa đăng nhập CLI. Hãy mở terminal, đăng nhập engine theo hướng dẫn của chính nó, rồi mở lại app. Với engine dạng API, kiểm tra lại thông tin trong Settings → Engines.

Lệnh git, npm hoặc uv báo không tìm thấy. Công cụ chưa cài hoặc terminal chưa nhận đường dẫn mới. Cài công cụ còn thiếu, đóng terminal rồi mở lại. Kiểm tra bằng node --version để chắc là bản 22 trở lên.

Terminal
node --version

Gõ npm run app nhưng báo không tìm thấy kịch bản. Rất có thể bạn đang đứng sai thư mục. Lệnh phải chạy trong thư mục suparagent/desktop, không phải thư mục gốc.

Windows hoặc macOS cảnh báo khi mở bộ cài. README ghi bộ cài desktop là bản thử nghiệm và chưa ký số. Chỉ tải từ trang Releases chính thức của repo, và nếu không yên tâm thì chạy từ mã nguồn như hướng dẫn ở trên.

Routine không chạy đúng giờ. Routine chạy ở backend, nên nếu backend tắt thì lịch cũng không chạy. Giữ app hoặc server luôn mở trong giờ hẹn.

Nếu vẫn kẹt, README chỉ hai nơi hỏi: cộng đồng Discord của dự án và trang GitHub Issues.

VII.Có nên dùng không

Điểm mạnh. Bạn giữ quyền kiểm soát: mọi hành động quan trọng đều qua phê duyệt, bộ nhớ xem và sửa được, dữ liệu trên desktop hoặc server tự host nằm ở máy của bạn, khoá API lưu qua Suparagent được mã hoá. Bạn chọn engine tuỳ ý, kể cả mô hình chạy cục bộ. Giấy phép Apache-2.0 cho phép dùng và chỉnh sửa thoải mái.

Giới hạn. README nói thẳng dự án còn sớm và thay đổi liên tục. Server tự host chỉ có một chủ sở hữu (có thể mời đồng đội, nhưng cùng dùng chung agent, hội thoại và bộ nhớ). Việc giao việc nhóm còn mới và cần Claude hoặc Codex cho trưởng nhóm. Máy tính Docker, công cụ trình duyệt và bản macOS gốc đều là thử nghiệm. Bộ cài desktop chưa ký số, app điện thoại chưa có iOS và chưa có thông báo đẩy. Đặt cạnh nhau, bạn nên thử trên việc ít rủi ro trước, chưa nên giao việc quan trọng.

Khi nào chọn cách khác. Nếu bạn chỉ cần một khung chat đơn giản với một mô hình, dùng thẳng công cụ của nhà cung cấp sẽ nhẹ hơn. Nếu bạn không muốn tự cài và bảo trì, README có nhắc bản web trả phí do dự án vận hành riêng, nhưng đó là sản phẩm tách biệt với phần mã nguồn mở và dữ liệu khi đó do dịch vụ đó xử lý. Còn nếu bạn thích thử nghiệm, muốn đội agent làm việc có kiểm soát và không ngại một sản phẩm đang hoàn thiện, Suparagent đáng để cài thử.

4.7/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn khô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. Tuy nhiên README ghi Suparagent không kèm mô hình hay gói đăng ký, nên bạn vẫn có thể phải trả cho nhà cung cấp engine. Bản web do dự án vận hành riêng có các gói tính phí và một gói xem thử.

Có cần GPU không?

Tư liệu không nêu yêu cầu GPU hay cấu hình phần cứng. Nếu bạn dùng mô hình chạy cục bộ qua Ollama hoặc LM Studio thì phần cứng phụ thuộc vào mô hình đó, nhưng README không đưa số liệu cụ thể.

Chạy được trên Windows không?

README chưa liệt kê rõ hệ điều hành cho bản desktop, nhưng repo có file run-desktop.bat và README nhắc tới bộ cài desktop kèm bản macOS gốc dạng thử nghiệm. Bạn nên xem trang Releases và hướng dẫn cài desktop trong thư mục docs/ của repo để biết chắc.

Dữ liệu của tôi có an toàn không?

Với desktop và tự host, hội thoại, ghi chú, routine và cài đặt lưu ở thư mục dữ liệu hoặc cơ sở dữ liệu của bạn, tệp làm việc nằm ở thư mục bạn chỉ định, khoá API lưu qua Suparagent được mã hoá. Tuy vậy, mỗi lượt trả lời engine nhận lời nhắc và ngữ cảnh cần thiết; nếu engine là dịch vụ đám mây 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?

README nói bạn chọn mức tự do cho agent: Ask first, Accept edits, Approve for me hoặc Plan only, và có thể xem lại hoạt động công cụ cùng quyết định duyệt. Routine không bao giờ tự duyệt một hành động. Dù vậy, hãy bắt đầu bằng Ask first khi mới dùng.

Dùng được với những engine AI nào?

Claude Code, Codex CLI, Gemini CLI, Gemini qua Antigravity, Cursor, agent dòng lệnh dùng 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; ví dụ nhập ảnh và máy tính của agent không phải engine nào cũng hỗ trợ.

Có 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, cho phép 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 app mới thử trên Android, chưa thử trên iOS, chưa có thông báo đẩy và chưa phát hành trên cửa hàng ứng dụng.

Chuyển nhanh tới mục

  1. I.Suparagent làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Chuẩn bị công cụ nền
    2. B.Tải mã nguồn
    3. C.Chạy ứng dụng
    4. D.Chọn engine, workspace và chế độ duyệt
    5. E.Cách khác: tự dựng server hoặc dùng bản cài sẵn
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Tổng hợp báo cáo dự án hằng tuần
    2. B.Biến việc lặp lại thành routine
    3. C.Chủ shop theo dõi việc cần xử lý trong ngày
    4. D.Lập trình viên dùng agent với mô hình chạy trên máy
  6. VI.Lỗi hay gặp và cách xử lý
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.