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

Suparagent: đồng nghiệp AI tự host, có duyệt trước khi làm — hướng dẫn cài đặt và dùng

12 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 tự host, có duyệt trước khi làm — 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) để tạo các đồng nghiệp AI: mỗi agent có tên, nhiệm vụ, thư mục làm việc, trí nhớ và lịch chạy định kỳ. Bạn tự mang engine AI của mình (Claude Code, Codex, Gemini CLI, Ollama…), repo không kèm mô hình. Bản desktop chạy từ mã nguồn bằng vài lệnh, cần Node.js 22+ và uv, nên hơi kỹ thuật với người mới nhưng không quá khó.

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 mỗi người một nhiệm vụ và một thư mục làm việc, rồi cho họ phối hợp xử lý công việc thật. Hội thoại, trí nhớ, lịch chạy định kỳ và các lần xin duyệt đều nằm chung một chỗ. Dự án mã nguồn mở, viết chủ yếu bằng Python, giấy phép Apache-2.0, hiện có khoảng 7.041 sao và 913 fork.

Bạn nên xem qua repo này nếu muốn dùng AI như một nhóm nhân viên chứ không chỉ một khung chat. Ví dụ: một agent nghiên cứu, một agent biên tập, một agent trưởng nhóm giao việc cho hai người kia. Chủ shop, nhân viên văn phòng cần báo cáo định kỳ, hay lập trình viên muốn tự host đều dùng được. Điểm đáng giá nhất là cơ chế duyệt: bạn chọn mức tự do cho agent, và các routine (việc chạy theo lịch) không bao giờ tự phê duyệt hành động thay bạn.

Cần nói thẳng một điều: Suparagent không kèm mô hình AI hay gói thuê bao nào. Bạn phải mang engine và tài khoản nhà cung cấp của mình, và chi phí dùng mô hình là bạn trả cho nhà cung cấp đó. Dự án cũng ghi rõ là đang phát triển tích cực, nhiều phần còn 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

Không gian làm việc mã nguồn mở cho các agent AI có tên, trí nhớ, lịch chạy và chỉ hành động sau khi bạn đồng ý. Chạy trên máy hoặc server của bạn.

★ 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à các tính năng chính, kèm lợi ích thực tế khi dùng.

  • 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 phê duyệt. 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 nhiều agent trong phòng chung. Việc này giúp bạn chia một yêu cầu lớn thành nhiều việc nhỏ. Trưởng nhóm hiện cần dùng Claude hoặc Codex.
  • Giữ ngữ cảnh lâu dài. Agent có thể lưu ghi chú, nhớ lại ghi chú và hội thoại liên quan, tìm lại lịch sử. Bạn xem và sửa được những gì chúng nhớ. Nhờ vậy bạn không phải giải thích lại bối cảnh mỗi lần.
  • Chạy việc theo lịch. Routine chạy theo lịch, theo webhook hoặc chạy thủ công. Bạn xem kết quả từng lần và trả lời các yêu cầu xin duyệt. Routine chạy trong backend, nên backend phải luôn bật.
  • Chọn mức tự do cho agent. Có các 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). Bạn xem lại hoạt động công cụ và các quyết định duyệt trong ứng dụng.
  • Kết nối ứng dụng và công cụ. Bạn kết 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 được chọn. Mọi thay đổi vẫn chờ bạn duyệt. Ngoài ra có thể thêm từng công cụ lẻ từ MCP Marketplace.
  • 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. Nó có thể hiện thêm Gmail và lịch ở chế độ chỉ đọc.
  • Bảng công việc và lịch. Giao việc, hẹn chạy một lần, xem lại các hội thoại và lần thử.
  • Kỹ năng và mẫu. Lưu skill (hướng dẫn bạn chọn cho một tin nhắn) và tạo agent từ mẫu có sẵn.
  • Ứng dụng đ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 một lần 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 để 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 tệp trong thư mục làm việc, xuất lịch sử.

Về engine, bạn dùng cái mình đã có: Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent dòng lệnh khác theo giao thức ACP, OpenRouter, hoặc API tương thích OpenAI như Ollama và LM Studio. Công cụ khả dụng tuỳ engine; ví dụ không phải engine nào cũng nhận ảnh hay dùng được máy tính riêng của agent.

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 (trang của uv: docs.astral.sh/uv).
  • Ít nhất một engine có sẵn trên cùng máy tính. Nếu dùng engine dạng dòng lệnh (CLI), bạn cài nó và đăng nhập trước khi mở ứng dụng. Nếu dùng engine qua API, bạn 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à tính năng này là tuỳ chọn.
  • Git để tải mã nguồn về.

Về hệ điều hành, README không liệt kê chi tiết cho bản desktop. Trong repo có file run-desktop.bat, nhưng README chưa giải thích nó, nên mình không khẳng định gì thêm. README nói thêm rằng trình cài đặt desktop còn thử nghiệm, chưa ký số và mới được kiểm chứng ở số nền tảng hạn chế. Bản chạy server tự host cần máy chủ Linux, HTTPS, Docker (hoặc Node.js và uv) và một engine.

Mình cũng nhắc lại là Suparagent không có mô hình đi kèm. Bạn cần sẵn tài khoản hoặc khoá của một nhà cung cấp AI.

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

  1. Chuẩn bị công cụCài Node.js 22+, uv, Git và một engine AI đã đăng nhập
  2. Tải mã nguồnDùng git clone để lấy repo về máy
  3. Vào thư mục desktopDùng cd để đứng đúng thư mục
  4. Chạy ứng dụngGõ npm run app
  5. Cấu hình lần đầuChọn engine, thư mục làm việc và chế độ duyệt

A.Chuẩn bị công cụ trước

Kiểm tra máy bạn đã có Node.js từ phiên bản 22 trở lên, đã cài uv và Git. Nếu dùng engine dạng CLI như Claude Code hay Codex, hãy cài và đăng nhập nó trước, vì README yêu cầu làm việc này trước khi mở ứng dụng. Chỗ người mới hay vấp là cài xong engine nhưng chưa đăng nhập, rồi ứng dụng báo engine chưa sẵn sàng.

Bước này không có lệnh riêng trong README, vì mỗi công cụ có cách cài riêng. Bạn xem hướng dẫn trên trang của từng công cụ.

B.Tải mã nguồn và vào thư mục desktop

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:

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

Lệnh đầu tải toàn bộ mã nguồn về một thư mục tên suparagent. Lệnh thứ hai đi vào thư mục con desktop. Nhớ là phải chạy lệnh tiếp theo ngay trong thư mục desktop, không phải thư mục ngoài.

C.Chạy ứng dụng

Terminal
npm run app

Đây là lệnh README ghi để mở ứng dụng desktop. Lần chạy đầu có thể mất thời gian vì cần chuẩn bị môi trường. Mình không có thêm thông tin về những gì lệnh này tải về, nên bạn hãy kiên nhẫn đợi và đọc thông báo trong terminal nếu có lỗi.

D.Cấu hình lần đầu

Lần mở đầu tiên, ứng dụng yêu cầu bạn chọn engine, thư mục làm việc (workspace) và chế độ duyệt (approval mode). Sau đó README gợi ý bốn việc:

  1. Mở Settings → Engines và xác nhận có một engine ở trạng thái sẵn sàng.
  2. Tạo một agent với tên, nhiệm vụ rõ ràng và một thư mục làm việc.
  3. 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.
  4. Thêm đồng đội hoặc tạo routine khi muốn chia việc hay lặp việc.

Nếu muốn thử bản cài sẵn, README trỏ đến trang Releases của repo. Tuy nhiên trình cài đặt còn thử nghiệm và chưa ký số, nên Windows hoặc macOS có thể cảnh báo.

E.Muốn tự host trên server?

Trong repo có Dockerfile, compose.yaml và thư mục deploy/. Nhưng README chưa ghi cách cài bản server, chỉ nói có hướng dẫn riêng. Bạn xem mục Self-hosting trong thư mục docs/ của repo và làm theo đó, đừng tự đoán lệnh.

Suparagent gửi nội dung cuộc trò chuyện 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à engine đọc) cho 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. Hãy bắt đầu với chế độ Ask first và một thư mục làm việc chỉ chứa tài liệu bạn sẵn lòng chia sẻ.

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

README không có lệnh kiểm tra riêng, nên cách tốt nhất là đi qua các bước đầu tiên của ứng dụng:

  • Cửa sơn mở lên và cho bạn chọn engine, workspace, chế độ duyệt 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à gửi tin nhắn đầu tiên, agent trả lời.
  • Ở chế độ Ask first, khi agent định làm việc cần duyệt (ví dụ sửa tệp), ứng dụng dừng lại và hỏi bạn.

Nếu cả bốn điều trên đúng, bạn đã cài thành công. Nếu engine không hiện là sẵn sàng, hãy xem phần lỗi thường gặp bên dưới.

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

Phần dưới bám theo những gì README mô tả. Các prompt là ví dụ mình đề xuất, bạn sửa theo công việc của mình.

Hãy giao việc như với nhân viên mới: nhiệm vụ rõ, thư mục riêng, và mọi việc quan trọng đều qua tay bạn duyệt.

Ông T

A.Báo cáo dự án hằng tuần cho nhân viên văn phòng

Bối cảnh: bạn quản lý một dự án, mỗi tuần phải tổng hợp ghi chú và báo cáo rải rác trong một thư mục. Đây chính là ví dụ README đưa ra.

Cách làm: tạo một agent trưởng nhóm và hai chuyên gia, chẳng hạn người nghiên cứu và người biên tập. Cho cả ba dùng chung thư mục dự án, và đặt engine của trưởng nhóm là Claude hoặc Codex. Sau đó gõ:

text
Hãy soạn bản tóm tắt dự án tuần này từ các ghi chú và báo cáo trong thư mục. Giao phần đọc tài liệu cho người nghiên cứu, phần viết lại cho người biên tập, rồi ghép lại cho mình.

Kết quả: trưởng nhóm chia nhỏ yêu cầu và giao cho các chuyên gia. Mỗi người làm trong một hội thoại riêng rồi trả kết quả về. 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 hằng tuần và xem lại từng lần chạy.

B.Dọn việc đầu ngày bằng màn hình Today

Bối cảnh: chủ shop nhỏ có vài agent chạy việc nền (soạn nháp trả lời, tổng hợp ghi chú) và không muốn mở từng cuộc trò chuyện để xem.

Cách làm: mỗi sáng mở màn hình Today. Ở đó có các yêu cầu duyệt đang chờ, câu hỏi từ agent, kết quả routine, lỗi engine và việc đến hạn. Nếu bạn đã kết nối Gmail và Google Calendar, nó có thể hiện thêm thư và lịch ở chế độ chỉ đọc.

Kết quả: bạn nhìn một chỗ là biết việc nào cần mình quyết, việc nào đã xong. Routine không bao giờ tự phê duyệt hành động, nên mọi bước nhạy cảm vẫn đợi bạn.

C.Giao việc có kiểm soát cho lập trình viên

Bối cảnh: lập trình viên muốn một agent hỗ trợ trong một thư mục mã nguồn, nhưng không muốn nó tự sửa tệp lung tung.

Cách làm: tạo agent với thư mục làm việc là dự án đó, chọn chế độ Plan only để chỉ xem kế hoạch, hoặc Ask first để duyệt từng hành động. Nếu dùng Claude, Codex hoặc Cursor, có thể thử Approve for me khi đã tin tưởng. Ví dụ prompt:

text
Đọc thư mục này và đề xuất kế hoạch dọn lại phần xử lý lỗi. Chưa sửa gì, chỉ liệt kê các bước.

Kết quả: bạn nhận kế hoạch, xem lại hoạt động công cụ và các quyết định duyệt trong ứng dụng, rồi mới cho phép bước tiếp theo.

D.Dùng model chạy trên máy mình

Bối cảnh: bạn muốn thử mà không muốn trả phí cho dịch vụ trên mạng, hoặc không muốn dữ liệu đi ra ngoài.

Cách làm: README nói có thể dùng API tương thích OpenAI như Ollama hoặc LM Studio, cấu hình trong Settings → Engines. Bạn tạo agent dùng engine đó và giao việc đơn giản như tóm tắt tệp văn bản.

Kết quả: agent chạy với mô hình cục bộ. Lưu ý là một số tính năng (như máy tính riêng của agent, nhập ảnh, nhóm agent cần Claude hoặc Codex) tuỳ vào engine, nên với mô hình cục bộ có thể không đủ.

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

  • Lệnh npm run app báo không tìm thấy hoặc báo lỗi phiên bản. Thường do Node.js cũ hơn 22 hoặc bạn đang đứng sai thư mục. Kiểm tra phiên bản Node, rồi chắc chắn terminal đang ở thư mục suparagent/desktop.
  • Thiếu uv. README yêu cầu uv, nên nếu terminal báo không có lệnh uv, hãy cài uv theo trang hướng dẫn của nó rồi mở lại terminal.
  • Engine không hiện là sẵn sàng. Với engine dạng CLI, README nói phải cài và đăng nhập trước khi mở ứng dụng. Hãy thoát ứng dụng, đăng nhập engine ngoài terminal, rồi mở lại. Với engine qua API, kiểm tra lại cấu hình trong Settings → Engines.
  • 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 máy hoặc tắt ứng dụng thì lịch sẽ không chạy. Muốn chạy đều, README gợi ý dùng server tự host.
  • Cảnh báo khi mở file cài đặt. Trình 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 không yên tâm, dùng cách chạy từ mã nguồn ở trên.

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

Điểm mạnh. Bạn giữ dữ liệu trong tay: với bản desktop và tự 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 máy bạn, tệp làm việc nằm trong thư mục bạn chỉ định, khoá API lưu qua Suparagent được mã hoá. Bạn chọn engine tuỳ ý, không bị khoá vào một hãng. Cơ chế duyệt rõ ràng và routine không tự phê duyệt là điểm cộng lớn cho người dùng doanh nghiệp nhỏ.

Giới hạn. Chính README ghi dự án còn sớm và đang thay đổi. Bản 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. Nhóm agent còn mới và trưởng nhóm cần Claude hoặc Codex. Ứ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. Docker, công cụ trình duyệt và bản macOS gốc đều là thử nghiệm. Ứng dụng kết nối qua Composio mới được kiểm thử với dịch vụ giả lập, chưa thử với dịch vụ thật. Cài đặt cũng đòi hỏi quen terminal.

Khi nên 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 nhiều. Nếu cần hệ thống ổn định cho công việc quan trọng ngay, hãy cân nhắc kỹ vì README khuyên xem phần hạn chế trước khi dựa vào nó. Còn nếu bạn muốn thử nhanh mà không cài gì, có bản dịch vụ trên mạng, nhưng đó là sản phẩm riêng, tính phí riêng và do Suparagent vận hành.

Tóm lại, đây là repo đáng thử cho người muốn có một nhóm AI có kiểm soát, chấp nhận còn thô, và có sẵn một engine để cắm vào. Hãy bắt đầu nhỏ: một agent, một thư mục thử, chế độ Ask first.

4.1/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?

Phần mã nguồn mở (bản desktop và tự host) dùng giấy phép Apache-2.0 và bạn có thể tự chạy. Tuy nhiên repo không kèm mô hình AI, nên bạn vẫn phải trả phí cho nhà cung cấp engine nếu dịch vụ đó tính phí. Ngoài ra có bản dịch vụ trên mạng là sản phẩm riêng với các gói trả phí.

Cần GPU hoặc máy mạnh không?

README không nêu yêu cầu GPU. Tuỳ bạn chọn engine: nếu dùng dịch vụ trên mạng thì máy không cần mạnh, còn dùng mô hình cục bộ qua Ollama hay LM Studio thì tài nguyên phụ thuộc mô hình đó. Tư liệu chưa có thông tin cụ thể về cấu hình phần cứng.

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

README không liệt kê chi tiết hệ điều hành cho bản desktop. Trong repo có file run-desktop.bat, nhưng README chưa giải thích nó. README chỉ nói trình cài đặt còn thử nghiệm và mới được kiểm chứng trên số nền tảng hạn chế, còn bản server 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ú, routine, cài đặt lưu trên máy hoặc server của bạn, khoá API lưu qua Suparagent được mã hoá. Tuy nhiên engine bạn chọn sẽ nhận câu hỏi và ngữ cảnh cần thiết cho mỗi lượt trả lời, và nếu đó là dịch vụ trên mạng thì dữ liệu thuộc đ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?

Tuỳ chế độ bạn chọn: Ask first, Accept edits, Approve for me (Claude, Codex, Cursor) hoặc Plan only. Riêng routine thì không bao giờ tự phê duyệt hành động, bạn vẫn phải trả lời các yêu cầu xin duyệt.

Dùng engine nào được?

README liệt kê Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent dòng lệnh dùng ACP, OpenRouter và 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à trưởng nhóm agent cần dùng Claude hoặc Codex.

Cài bản server tự host như thế nào?

README chưa ghi lệnh cài bản server, chỉ trỏ tới hướng dẫn Self-hosting trong tài liệu của repo. Repo có Dockerfile, compose.yaml và thư mục deploy, nhưng bạn nên làm theo hướng dẫn trong thư mục docs thay vì tự đoán lệnh. README cũng ghi bản server cần Linux và HTTPS.

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ụ trước
    2. B.Tải mã nguồn và vào thư mục desktop
    3. C.Chạy ứng dụng
    4. D.Cấu hình lần đầu
    5. E.Muốn tự host trên server?
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Báo cáo dự án hằng tuần cho nhân viên văn phòng
    2. B.Dọn việc đầu ngày bằng màn hình Today
    3. C.Giao việc có kiểm soát cho lập trình viên
    4. D.Dùng model chạy trên máy mình
  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ỏ.