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

Suparagent: lập đội đồ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: lập đội đồ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ở (Apache-2.0, chủ yếu viết bằng Python) để tạo các «đồng nghiệp AI» có tên, có việc riêng, có trí nhớ, chạy theo lịch và chờ bạn duyệt trước khi làm. Bạn tự mang engine AI của mình (Claude Code, Codex, Gemini CLI, Ollama…). Bản desktop chạy từ mã nguồn bằng ba lệnh, cần Node.js 22 trở lên và uv; mức độ khó vừa phải.

Suparagent là một không gian làm việc mã nguồn mở, nơi bạn tạo ra các «đồng nghiệp AI» có tên riêng, giao cho mỗi bạn một công việc và một thư mục làm việc, rồi để họ phối hợp hoàn thành 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ỗ. Bạn có thể 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 kinh doanh, văn phòng muốn có trợ lý AI 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 muốn một «bảng điều khiển» chung cho nhiều công cụ AI dòng lệnh. Nhóm ba là người muốn dữ liệu nằm trên máy mình thay vì đẩy lên dịch vụ của bên khác. Hiện repo có khoảng 7.000 sao và 900 fork, vẫn được cập nhật trong vài tháng gần đây.

Điểm đáng giá nhất: agent không tự ý hành động. Bạn chọn mức tự do, ví dụ «Ask first» để dừng lại hỏi trước khi làm việc cần quyền, và ngay cả khi chạy theo lịch, routine cũng không bao giờ tự duyệt thay bạn. Mình đã làm một video ngắn giới thiệu repo này, bạn xem video bên dưới nhé.

Ứng dụng

Anil-matcha/suparagent

Suparagent là 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 định kỳ và phải xin 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, mình giải thích theo lợi ích bạn nhận được.

  • Tạo agent và đội nhóm. 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. 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. Lợi ích: bạn không phải ôm cả một yêu cầu to vào một cuộc chat; việc được chia nhỏ và chạy ở các hội thoại riêng. Theo README, trưởng nhóm cần dùng Claude hoặc Codex.
  • Giữ ngữ cảnh hữu ích. Agent có thể 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à sửa được những gì agent nhớ. Lợi ích: đỡ 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 tay. Bạn xem kết quả từng lần và trả lời các yêu cầu duyệt. Lợi ích: việc lặp lại hằng tuần được tự động hoá mà vẫn trong tầm kiểm soát.
  • Chọn mức tự do cho agent. Có bốn chế độ: Ask first, Accept edits, Approve for me (dành cho Claude, Codex và Cursor) và Plan only. Bạn xem lại hoạt động công cụ và các quyết định duyệt ngay trong ứng dụng.
  • Kết nối công cụ và ứng dụng. Qua khoá Composio của chính bạn, bạn 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ụ 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, 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 cô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ử.
  • Kỹ năng và mẫu agent. Lưu lại các chỉ dẫn dùng đi dùng lại, tạo agent mới từ mẫu.
  • Dùng từ điện thoại. Ghép ứng dụng đ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ệnh 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 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ử.

Suparagent KHÔNG kèm sẵn mô hình AI hay gói đăng ký mô hình. Bạn mang tài khoản của nhà cung cấp mình đang dùng.

II.Cần chuẩn bị gì

Với bản desktop chạy từ mã nguồn, README nêu các yêu cầu sau:

  • Node.js 22 trở lên.
  • uv (công cụ quản lý Python; trang hướng dẫn: docs.astral.sh/uv).
  • Ít nhất một engine AI có sẵn trên cùng máy. Nếu dùng engine dòng lệnh (CLI), bạn phải cài và đăng nhập engine đó trước khi mở ứng dụng. Hoặc bạn cấu hình engine dùng API trong Settings → Engines.
  • Docker chỉ cần nếu muốn dùng «máy tính cách ly» cho agent (tuỳ chọn).

Các engine được liệt kê: Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, công cụ dòng lệnh khác dùng giao thức ACP, OpenRouter, và API tương thích OpenAI như Ollama hoặc LM Studio. Công cụ khả dụng thay đổi theo engine, ví dụ không phải engine nào cũng nhận ảnh hay dùng được máy tính cách ly.

Nếu chọn tự dựng máy chủ, README ghi cần máy chủ Linux, HTTPS, Docker (hoặc Node.js và uv) và một engine. README không nói rõ yêu cầu phần cứng như GPU hay dung lượng RAM, nên mình không đoán.

Suparagent không đi kèm mô hình AI. Dùng engine của nhà cung cấp bên ngoài có thể tốn tiền theo lượng dùng. Hãy kiểm tra gói cước hoặc hạn mức của tài khoản trước khi cho agent chạy theo lịch.

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

Chỉ có ba lệnh cho bản desktop từ mã nguồn. Phần chuẩn bị engine mới là chỗ tốn thời gian nhất.

  1. Cài công cụ nềnCó Node.js 22+ và uv trên máy
  2. Chuẩn bị engineCài và đăng nhập một engine AI, hoặc chuẩn bị API
  3. Tải mã nguồngit clone repo về máy
  4. Chạy ứng dụngVào thư mục desktop và chạy npm run app
  5. Cấu hình lần đầuChọn engine, thư mục làm việc, chế độ duyệt

A.Cài Node.js, uv và một engine

Kiểm tra Node.js bằng lệnh dưới đây, kết quả phải từ phiên bản 22 trở lên. Nếu thấp hơn, bạn cần nâng cấp trước.

Terminal
node --version

Với uv, bạn làm theo trang hướng dẫn chính thức của uv (README dẫn link tới docs.astral.sh/uv). Với engine, ví dụ bạn dùng Claude Code hoặc Codex CLI thì cài xong phải đăng nhập trước. Đây là chỗ người mới hay vấp: nếu chưa đăng nhập, Suparagent sẽ báo engine chưa sẵn sàng.

B.Tải mã nguồn

Mở terminal (trên Windows dùng PowerShell hoặc Git Bash; trên macOS/Linux dùng Terminal) ở 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ải toàn bộ mã nguồn về một thư mục tên suparagent. Bạn cần có Git trên máy.

C.Chạy ứng dụng desktop

Vào thư mục desktop và chạy ứng dụng:

Terminal
cd suparagent/desktop
npm run app

Lệnh cd đưa terminal vào đúng thư mục; npm run app là lệnh README cung cấp để mở ứng dụng. Hãy chắc là bạn đang đứng trong thư mục desktop khi chạy, nếu không npm sẽ báo không tìm thấy script.

D.Thiết lập 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 và chế độ duyệt. Nếu chưa chắc, hãy chọn Ask first để mọi hành động cần quyền đều dừng lại hỏi bạn.

E.Các cách chạy khác

README có bảng so sánh bốn cách chạy: bản desktop, máy chủ tự host, bản web có sẵn (dịch vụ riêng, trả phí) và bản dành cho người phát triển. Repo có Dockerfile và compose.yaml, nhưng README chưa ghi lệnh cài cho máy chủ tự host ngay trong trang đầu. Bạn xem mục hướng dẫn self-hosting trong thư mục docs/ của repo. Ngoài ra, README có nhắc trang Releases cho các bộ cài desktop; các bộ cài này còn thử nghiệm và chưa được ký số.

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

Theo README, bạn kiểm tra theo thứ tự sau:

  1. Ứng dụng mở lên và cho bạn chọn engine, thư mục làm việc, chế độ duyệt ở lần đầu.
  2. Vào Settings → Engines và xác nhận có một engine ở trạng thái sẵn sàng.
  3. 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.
  4. Bắt đầu chat với agent đó. Nếu chọn Ask first, bạn sẽ thấy ứng dụng dừng lại xin duyệt trước khi làm việc cần quyền. Đó là dấu hiệu mọi thứ hoạt động đúng.

Nếu engine không sẵn sàng, quay lại bước cài và đăng nhập engine. README không mô tả thông báo lỗi cụ thể, nên bạn xem trang engine trong thư mục docs/ hoặc hỏi trên Discord của dự án.

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

Các tình huống dưới đây bám đúng khả năng README nêu. Câu lệnh mẫu là gợi ý của mình, bạn tự điều chỉnh theo công việc.

A.Chủ shop tổng hợp báo cáo bán hàng hằng tuần

Bạn bán hàng online và mỗi tuần có vài tệp ghi chú, báo cáo doanh số trong một thư mục. Hãy tạo agent trưởng nhóm (engine Claude hoặc Codex) cùng 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ùng trỏ vào thư mục đó. Sau đó nhắn cho trưởng nhóm:

text
Đọc các ghi chú và báo cáo trong thư mục này, tổng hợp bản tóm tắt tuần: sản phẩm bán chạy, vấn đề khách phàn nàn, 3 việc nên làm tuần tới.

Trưởng nhóm sẽ chia nhỏ việc, giao cho hai agent kia chạy trong các hội thoại riêng, rồi gom lại thành một bản. Khi quy trình đã ổn, bạn biến nó thành routine chạy hằng tuần và xem lại kết quả mỗi lần. Đây cũng chính là ví dụ mà README đưa ra.

Agent làm việc, còn quyền quyết định vẫn nằm ở bạn.

Ông T

B.Nhân viên văn phòng theo dõi việc cần xử lý

Bạn là nhân viên hành chính, mỗi sáng phải xem thư và lịch. Nếu bạn nối Gmail và Google Calendar qua khoá Composio của mình, màn hình Today gom các việc cần chú ý và có thể hiện thư, lịch ở chế độ chỉ đọc. Kết quả: mở một màn hình là thấy hôm nay cần duyệt gì, trả lời gì, việc nào đến hạn. Lưu ý README ghi rõ phần kết nối ứng dụng qua Composio mới được thử với dịch vụ giả lập, chưa phải dịch vụ thật, nên đừng giao việc quan trọng khi chưa thử kỹ.

C.Lập trình viên giao việc cho nhiều agent trên cùng dự án

Bạn đã dùng Claude Code hoặc Codex trên máy. Hãy tạo mỗi agent một vai: một người đọc mã, một người viết ghi chú thay đổi. Chọn chế độ Plan only để agent chỉ lập kế hoạch, hoặc Accept edits khi bạn tin tưởng việc sửa tệp. Dùng bảng công việc để giao việc, xem lại các lần thử của từng agent. Kết quả: bạn có chỗ tập trung để theo dõi và duyệt thay vì mở nhiều cửa sổ terminal.

D.Người dùng cần xử lý từ xa bằng điện thoại

Nếu bạn tự dựng máy chủ, bạn ghép ứng dụng điện thoại với máy chủ đó để chat, dừng một câu trả lời đang chạy, cho phép hoặc từ chối lệnh gọi công cụ khi đang ở ngoài. Kết quả: agent dừng chờ duyệt không còn nằm đó cả ngày. Hạn chế: README nói ứng dụng điện thoại mới thử trên giả lập Android và một điện thoại Android, chưa thử trên iOS, chưa có thông báo đẩy và chưa lên cửa hàng ứng dụng.

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

A.Engine không hiện «sẵn sàng»

Nguyên nhân thường gặp: chưa cài hoặc chưa đăng nhập engine dòng lệnh. README yêu cầu cài và đăng nhập trước khi mở ứng dụng. Cách xử lý: đăng nhập engine trong terminal, mở lại ứng dụng, rồi vào Settings → Engines kiểm tra. Hoặc cấu hình engine dùng API ở cùng màn hình.

B.Lệnh npm run app báo lỗi hoặc không chạy

Hai khả năng dễ xảy ra: bạn đang đứng sai thư mục (phải là suparagent/desktop), hoặc phiên bản Node.js thấp hơn 22. Chạy node --version để kiểm tra, nâng cấp nếu cần. Nếu vẫn lỗi, mở Issues trên GitHub của dự án và dán nguyên thông báo lỗi.

C.Bộ cài desktop bị cảnh báo khi mở

README nói các bộ cài còn thử nghiệm và chưa được 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. Quy trình cập nhật có kiểm tra SHA-256 nhưng không tự cài; bạn tự mở bộ cài. Đường cập nhật giữa các bản phát hành cũng chưa được kiểm chứng đầy đủ.

D.Routine không chạy theo lịch

README nói routine chạy trong backend, nên backend phải luôn chạy. Nếu bạn tắt máy hoặc đóng ứng dụng, lịch sẽ không chạy. Muốn lịch chạy ổn định, hãy cân nhắc tự dựng máy chủ và để nó chạy liên tục.

E.Agent dừng lại và «đứng yên»

Đây thường không phải lỗi: agent đang chờ bạn duyệt. Mở màn hình Today hoặc cuộc chat để xem yêu cầu duyệt và trả lời. Nếu bạn muốn ít bị hỏi hơn, hãy đổi chế độ, nhưng chỉ làm với agent và thư mục bạn tin tưởng.

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

Điểm mạnh. Mã nguồn mở theo giấy phép Apache-2.0. Dữ liệu hội thoại, ghi chú, routine và cài đặt nằm trong thư mục dữ liệu trên máy bạn hoặc cơ sở dữ liệu máy chủ của bạn; tệp làm việc nằm trong các thư mục bạn giao cho agent; khoá API lưu qua Suparagent được mã hoá. Hỗ trợ nhiều engine nên bạn không bị khoá vào một nhà cung cấp. Cơ chế duyệt rõ ràng, có nhiều mức tự do.

Giới hạn. Dự án còn sớm và thay đổi nhanh. Bản desktop và máy chủ tự host đều ở mức thử nghiệm. Máy chủ tự host chỉ có một chủ sở hữu có thể mời đồng đội, mọi người dùng chung agent, hội thoại và trí nhớ; nó không phải dịch vụ nhiều tổ chức. Ủy quyền đội nhóm còn mới, trưởng nhóm phải dùng Claude hoặc Codex. Máy tính cách ly bằng Docker, công cụ trình duyệt và bản macOS gốc đều thử nghiệm và tuỳ chọn. MCP Marketplace, máy tính đám mây và chuyển âm thanh thành chữ chưa được kiểm chứng trên dịch vụ thật.

Về dữ liệu. Khi agent trả lời, engine bạn chọn nhận câu lệnh và 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. Nếu engine là dịch vụ trên mạng, thông tin đó theo điều khoản của nhà cung cấp ấy. Đừng đưa tài liệu nhạy cảm cho engine mà bạn chưa tin.

Chi phí. Phần mã nguồn mở không tính phí, nhưng dùng mô hình có thể tốn tiền. Bản web có sẵn là sản phẩm riêng với các gói trả phí, bạn xem trang giá của họ nếu quan tâm.

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 là đủ. Nếu bạn cần dịch vụ ổn định cho cả công ty nhiều bộ phận, bản tự host hiện chưa phải lựa chọn phù hợp. Nếu bạn dùng iPhone và muốn thông báo đẩy, ứng dụng điện thoại hiện chưa đáp ứng. Còn nếu bạn muốn thử một đội agent có kiểm soát, chạy ngay trên máy mình, thì Suparagent đáng để bạn thử với một thư mục nhỏ, chế độ Ask first, rồi mở rộng dần.

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à máy chủ tự host) theo giấy phép Apache-2.0. Tuy nhiên Suparagent không kèm mô hình AI, nên bạn vẫn phải có tài khoản engine và việc dùng mô hình có thể tốn tiền. Bản web có sẵn là sản phẩm riêng với gói Free preview và các gói trả phí.

Cần GPU hay máy cấu hình mạnh không?

Tư liệu không nêu yêu cầu GPU hay RAM. Yêu cầu được ghi là Node.js 22+, uv và một engine. Nếu bạn dùng engine chạy cục bộ như Ollama hoặc LM Studio thì cấu hình máy phụ thuộc vào mô hình bạn chọn, README không nói cụ thể.

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

Repo có tệp run-desktop.bat, gợi ý có hỗ trợ Windows. Tuy nhiên README ghi các bộ cài desktop chưa được ký số và mới kiểm chứng nền tảng ở mức hạn chế, và bản macOS gốc chỉ là bản xem trước thử nghiệm. Hãy tự thử và xem trang Releases.

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, cài đặt nằm 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 mỗi lượt trả lời, engine bạn chọn nhận câu lệnh 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 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 không bao giờ tự duyệt một hành động thay bạn. Bạn có thể xem lại hoạt động công cụ và quyết định duyệt trong ứng dụng.

Dùng được những engine AI 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ông phải engine nào cũng hỗ trợ đủ tính năng; ví dụ trưởng nhóm cần dùng Claude hoặc Codex.

Khác gì dùng thẳng Claude Code hoặc Codex?

Suparagent không thay thế engine mà đứng phía trên: nó thêm agent có tên, trí nhớ, routine, bảng việc, phối hợp nhiều agent và màn hình duyệt chung. README không so sánh chi tiết hơn, nên mình không khẳng định thêm.

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.Cài Node.js, uv và một engine
    2. B.Tải mã nguồn
    3. C.Chạy ứng dụng desktop
    4. D.Thiết lập lần đầu
    5. E.Các cách chạy khác
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop tổng hợp báo cáo bán hàng hằng tuần
    2. B.Nhân viên văn phòng theo dõi việc cần xử lý
    3. C.Lập trình viên giao việc cho nhiều agent trên cùng dự án
    4. D.Người dùng cần xử lý từ xa bằng điện thoại
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Engine không hiện «sẵn sàng»
    2. B.Lệnh npm run app báo lỗi hoặc không chạy
    3. C.Bộ cài desktop bị cảnh báo khi mở
    4. D.Routine không chạy theo lịch
    5. E.Agent dừng lại và «đứng yên»
  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ỏ.