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

Suparagent: không gian làm việc cho đồng nghiệp AI — 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: không gian làm việc cho đồng nghiệp AI — 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 như đồng nghiệp: mỗi agent có tên, công việc, trí nhớ, lịch chạy và phải xin bạn duyệt trước khi hành động. Bạn có thể chạy bản desktop trên máy mình hoặc tự dựng server. Cài bản desktop cần Node.js 22+, uv và một engine AI có sẵn; README ghi chỉ ba lệnh, nhưng dự án vẫn đang thử nghiệm.

Suparagent là một ứng dụng mã nguồn mở giúp bạn tạo ra các “đồng nghiệp AI”: mỗi agent có tên riêng, một công việc rõ ràng, một thư mục làm việc, trí nhớ và lịch chạy. Điểm khác với việc chat AI thông thường là bạn quản lý cả nhóm agent ở một chỗ, và agent phải xin bạn duyệt trước khi làm những việc nhạy cảm.

Repo này hợp với người muốn giao việc lặp lại cho AI mà vẫn giữ quyền kiểm soát: nhân viên văn phòng làm báo cáo hằng tuần, chủ shop muốn có trợ lý theo dõi công việc, hoặc lập trình viên muốn tự host một “bàn làm việc” cho agent. Suparagent hiện có khoảng 7041 sao và 913 fork, giấy phép Apache-2.0.

Có một điều bạn cần biết trước: Suparagent không kèm sẵn mô hình AI nào. Bạn phải mang theo engine và tài khoản của riêng mình (ví dụ Claude Code, Codex CLI, Gemini CLI hoặc một API tương thích OpenAI). Tác giả cũng ghi rõ dự án đang phát triển tích cực và nhiều phần còn thử nghiệm. Bạn có thể xem video ngắn bên dưới để thấy bản demo trước khi cài.

Ứng dụng

Anil-matcha/suparagent

Suparagent là không gian làm việc cho các đồng nghiệp AI có tên, có trí nhớ, chạy theo lịch và chờ bạn duyệt trước khi làm. Mã nguồn mở, tự chạy trên máy 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, viết theo kiểu “bạn được lợi gì”.

  • 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ể có một agent trưởng nhóm giao 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. README ghi trưởng nhóm 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à 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ì agent nhớ, nên không sợ nó nhớ sai mà bạn không biết.
  • Chạy việc theo lịch (routine). Bạn tạo routine chạy theo lịch, qua webhook hoặc chạy thủ công. Mỗi kết quả bạn tự xem lại. README nhấn mạnh routine không bao giờ tự duyệt hành động thay bạn.
  • 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 và 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 ngay trong app.
  • Kết nối ứng dụng. Qua khóa Composio của chính bạn, có thể nối GitHub, Gmail, Google Calendar rồi cấp quyền cho một số agent Claude hoặc Codex. 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 lại việc cần bạn chú ý: yêu cầu duyệt, câu hỏi, kết quả routine, lỗi engine và công 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 các cuộc trò chuyện và các lần thử.
  • Kỹ năng và mẫu. Lưu skill (hướng dẫn bạn chọn dùng cho một tin nhắn) và tạo agent từ mẫu có sẵn, đỡ phải viết lại từ đầu.
  • Dùng trên đ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 gọi công cụ. README ghi app mới thử trên Android, chưa thử trên iOS.
  • Làm việc với tệp và lịch sử. Tìm kiếm cuộc trò chuyện, đí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 xác thực), duyệt hoặc tải tệp 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 (source checkout) và cần:

  • Node.js 22 trở lên.
  • uv (công cụ quản lý Python, README dẫn tới trang docs.astral.sh/uv để bạn cài).
  • Ít nhất một engine có sẵn trên cùng máy. Nếu dùng engine dạng dòng lệnh (CLI), bạn phải cài nó và đăng nhập trước khi mở app. Cũng có thể cấu hình engine dạng API trong Settings → Engines.
  • Docker chỉ cần nếu bạn muốn dùng các “máy tính cô lập” cho agent, và phần này là tùy chọn, còn thử nghiệm.
  • Git để tải mã nguồn về (lệnh git clone là lệnh phổ thông).

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

Về chi phí: bản mã nguồn mở không kèm mô hình. Dùng model của nhà cung cấp nào thì bạn trả tiền cho nhà đó. README không nói yêu cầu phần cứng cụ thể, và cũng không nói rõ hệ điều hành nào được hỗ trợ cho bản desktop, chỉ ghi trình cài đặt còn 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ế.

Chọn chế độ Ask first khi mới dùng. Agent có thể đọc và sửa tệp trong thư mục bạn giao, nên hãy trỏ nó vào một thư mục thử, đừng trỏ vào thư mục chứa dữ liệu quan trọng. Dùng engine dạng API cũng có thể tốn tiền theo lượt dùng.

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

  1. Cài điều kiệnNode.js 22+, uv 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 desktopcd vào suparagent/desktop
  4. Chạy appGõ npm run app
  5. Cấu hình lần đầuChọn engine, workspace và chế độ duyệt

A.Cài các thứ cần có

Cài Node.js phiên bản 22 trở lên và uv. Sau đó cài engine bạn định dùng. Nếu là CLI như Claude Code hay Codex, hãy đăng nhập xong rồi mới mở Suparagent. Đây là chỗ người mới hay vấp: app không tự đăng nhập hộ engine CLI, vì README ghi đăng nhập CLI nằm ở engine cài trên máy đó.

B.Tải mã nguồn về máy

Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) ở thư mục bạn muốn để dự án, rồi gõ:

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.

C.Vào thư mục desktop và chạy app

README ghi đúng hai lệnh sau:

Terminal
cd suparagent/desktop
npm run app

Lệnh đầu đưa terminal vào thư mục desktop. Lệnh thứ hai khởi động ứng dụng. Bạn phải chạy npm run app trong thư mục desktop, không phải thư mục gốc. Trong thư mục gốc repo còn có file run-desktop.bat, nhưng README không nhắc đến nó, nên mình chỉ dựa vào ba lệnh trên.

Về cài đặt dạng installer: README có nói trang Releases có các bộ cài desktop, nhưng đây là bản thử nghiệm và chưa ký số. Về self-hosting (tự dựng server), repo có Dockerfile và compose.yaml, nhưng README tóm tắt chưa chép lệnh cụ thể. Bạn xem mục Self-hosting guide trong thư mục docs của repo trước khi làm.

D.Thiết lập lần chạy đầu

Khi mở lần đầu, app yêu cầu chọn engine, workspace và chế độ duyệt. Sau đó làm theo thứ tự README:

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

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

README không đưa lệnh kiểm tra riêng, nên cách kiểm tra là đi qua đúng luồng ở trên:

  • Sau npm run app, cửa sổ ứng dụng mở ra và hỏi bạn chọn engine, workspace, chế độ duyệt.
  • Trong Settings → Engines, engine bạn cài hiển thị là đã sẵn sàng.
  • Bạn tạo được một agent, mở chat và nhận được câu trả lời. Nếu đang để Ask first, những hành động cần duyệt sẽ dừng lại hỏi bạn.

Cách thử nhanh: tạo agent tên “Trợ lý thử”, trỏ workspace vào một thư mục trống, rồi nhắn “Hãy liệt kê các tệp trong thư mục làm việc”. Nếu agent trả lời, hoặc hiện yêu cầu duyệt rồi trả lời sau khi bạn đồng ý, nghĩa là mọi thứ đã nối thông.

V.Dùng vào việc thậ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 thành một bản tóm tắt cho sếp. Đây chính là ví dụ README đưa ra.

Cách làm: 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 một thư mục dự án, đặt engine của trưởng nhóm là Claude hoặc Codex. Rồi nhắn cho trưởng nhóm:

text
Hãy chuẩn bị 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.

Kết quả: trưởng nhóm chia việc nhỏ, giao cho các chuyên gia, mỗi người làm trong một cuộc trò chuyện riêng rồi trả về cho 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ứ giao việc như giao cho một đồng nghiệp, nhưng người duyệt cuối cùng vẫn là bạn.

Ông T

B.Biến quy trình đã ổn thành routine

Bối cảnh: sau vài tuần, bản tóm tắt ở trên đã đúng ý bạn. Bạn không muốn ngồi nhắn lại mỗi tuần.

Cách làm: tạo một routine, chọn chạy theo lịch hằng tuần (hoặc webhook, hoặc thủ công), dùng lại câu lệnh đã hiệu quả. Nhớ rằng routine chạy trong backend nên backend phải luôn đang chạy.

Kết quả: mỗi tuần có một lần chạy mới, bạn mở app xem lại kết quả. Nếu routine cần làm gì đó cần duyệt, nó sẽ chờ bạn trả lời chứ không tự quyết.

C.Bắt đầu một ngày bằng màn hình Today

Bối cảnh: bạn có vài agent đang chạy và không muốn mở từng cuộc trò chuyện để xem cái nào đang chờ mình.

Cách làm: mở màn hình Today. Nơi này gom các yêu cầu duyệt, câu hỏi từ agent, kết quả routine, lỗi engine và việc đến hạn. Nếu đã nối Gmail và lịch, có thể xem thêm các mục chỉ đọc.

Kết quả: bạn biết ngay việc nào cần mình trả lời trước, thay vì lật từng chat. Phần Gmail và lịch dựa trên Composio, mà README ghi là mới thử với một dịch vụ giả lập, chưa thử với dịch vụ thật, nên hãy dùng thận trọng.

D.Tự host cho đội nhỏ

Bối cảnh: bạn là lập trình viên hoặc người phụ trách kỹ thuật, muốn agent và routine luôn sẵn sàng trên một server của mình, và mời vài đồng nghiệp dùng chung.

Cách làm: README mô tả server tự host cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine. Một người là chủ và có thể mời đồng đội, có vai trò và quyền riêng từng người. Hãy đọc hướng dẫn Self-hosting trong repo trước khi làm.

Kết quả: cả nhóm dùng chung agent, cuộc trò chuyện và trí nhớ trên server của bạn. Lưu ý đây chưa phải dịch vụ nhiều tổ chức, và README ghi đây vẫn là bản thử nghiệm.

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

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

Thường do engine CLI chưa cài hoặc chưa đăng nhập. Hãy mở terminal, kiểm tra engine đó chạy được ngoài app, đăng nhập xong rồi mở lại Suparagent và vào Settings → Engines. Nếu dùng engine API, kiểm tra lại cấu hình ở cùng màn hình đó.

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

Trước hết xem bạn có đang đứng đúng trong thư mục suparagent/desktop không. Sau đó kiểm tra Node.js bằng node --version, cần từ 22 trở lên, và kiểm tra uv đã cài. Nếu vẫn lỗi, tìm trong GitHub Issues của repo hoặc hỏi ở Discord, vì README chưa liệt kê thông báo lỗi cụ thể.

C.Trình cài đặt bị Windows hoặc macOS cảnh báo

README ghi bộ cài desktop là thử nghiệm và chưa ký số, nên hệ điều hành có thể cảnh báo. Đây là hành vi dự kiến. Nếu bạn không yên tâm, chạy từ mã nguồn theo ba lệnh ở trên thay vì cài bộ cài. Chỉ tải từ trang Releases chính thức của repo.

D.Tính năng không dùng được với engine đã chọn

Một số tính năng chỉ chạy với Claude hoặc Codex, như trưởng nhóm giao việc, kết nối ứng dụng qua Composio và chế độ Approve for me (thêm cả Cursor). Nếu mục nào mờ hoặc không hoạt động, hãy xem bảng khả năng của engine trong thư mục docs, hoặc đổi engine cho agent đó.

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

Routine chạy trong backend, nên nếu backend tắt (ví dụ bạn đóng app hoặc tắt máy) thì lịch sẽ không chạy. Hãy để ứng dụng hoặc server chạy đúng thời điểm đã hẹn. Nếu muốn chạy ổn định, tự host trên một server luôn bật là hợp lý hơn máy cá nhân.

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

Điểm mạnh. Bạn có một chỗ duy nhất để quản lý nhiều agent, trí nhớ, routine và các lần duyệt. Quyền kiểm soát nằm ở bạn: có nhiều mức duyệt, và routine không tự duyệt thay bạn. Dữ liệu bản desktop và tự host nằm ở máy hoặc server của bạn, khóa API lưu qua Suparagent được mã hóa. Bạn chọn được nhiều engine, gồm cả Ollama hay LM Studio, và giấy phép Apache-2.0 thoải mái.

Giới hạn. Dự án còn sớm và thay đổi nhanh. Trình cài đặt chưa ký số, đường cập nhật giữa các bản chưa được kiểm chứng đầy đủ. Máy tính cô lập bằng Docker, công cụ trình duyệt và bản macOS gốc đều là thử nghiệm. App điện thoại chưa thử trên iOS, chưa có thông báo đẩy. Kết nối ứng dụng qua Composio chưa được thử với dịch vụ thật. Phần nhiều tài liệu chi tiết nằm trong thư mục docs, bạn sẽ phải đọc thêm khi tự host.

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 đí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 đó chịu điều khoản của nhà cung cấp ấy.

Khi nào 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 là đủ và đơn giản hơn. Nếu bạn cần công cụ đã ổn định và có hỗ trợ chính thức cho công việc quan trọng, nên cân nhắc kỹ vì README tự khuyến cáo đọc phần hạn chế trước khi dựa vào nó. Còn nếu bạn thích thử nghiệm, muốn tự chủ dữ liệu và giao việc lặp lại cho một nhóm agent, Suparagent đáng để cài thử trên một thư mục không quan trọng.

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

Bản mã nguồn mở (desktop và tự host) dùng giấy phép Apache-2.0. Nhưng Suparagent không kèm mô hình AI, nên bạn vẫn phải có tài khoản engine của riêng mình và có thể mất phí theo nhà cung cấp. Ngoài ra có bản dịch vụ hosted riêng với gói Free preview, Starter 15 USD, Standard 49 USD và Pro 99 USD mỗi tháng.

Cần những gì để cài bản desktop?

README ghi cần Node.js 22 trở lên, uv và ít nhất một engine có sẵn trên cùng máy. Nếu dùng engine CLI thì phải cài và đăng nhập trước. Docker chỉ cần cho các máy tính cô lập của agent, là phần tùy chọn.

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

README không nêu rõ danh sách hệ điều hành được hỗ trợ cho bản desktop. Nó chỉ ghi bộ cài là thử nghiệm, chưa ký số và có kiểm chứng nền tảng hạn chế. Trong repo có file run-desktop.bat nhưng README không giải thích, nên hãy xem hướng dẫn desktop trong thư mục docs.

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

Với desktop và tự host, cuộc trò chuyện, ghi chú, routine và cài đặt lưu trong thư mục dữ liệu hoặc cơ sở dữ liệu của máy hay server bạn, còn khóa API lưu qua Suparagent được mã hóa. Tuy nhiên, engine bạn chọn vẫn nhận câu lệnh và ngữ cảnh của lượ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.

Có cần GPU không?

Tư liệu không nêu yêu cầu GPU hay phần cứng cụ thể. Vì Suparagent dùng engine bạn tự chọn, nhu cầu phần cứng phụ thuộc vào engine đó, ví dụ chạy mô hình cục bộ qua Ollama hay LM Studio sẽ khác với dùng API trên mạng.

Agent có tự làm mọi thứ mà không hỏi tôi không?

Không bắt buộc. Bạn chọn chế độ Ask first, Accept edits, Approve for me (cho Claude, Codex và Cursor) hoặc Plan only. README cũng ghi routine không bao giờ tự duyệt hành động thay bạn, và các thay đổi qua ứng dụng kết nối đều chờ bạn duyệt.

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 gọi công cụ, tạo và sửa agent. README ghi app 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 hay bản 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.Cài các thứ cần có
    2. B.Tải mã nguồn về máy
    3. C.Vào thư mục desktop và chạy app
    4. D.Thiết lập lần chạy đầu
  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.Biến quy trình đã ổn thành routine
    3. C.Bắt đầu một ngày bằng màn hình Today
    4. D.Tự host cho đội nhỏ
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Engine không hiện là sẵn sàng
    2. B.npm run app báo lỗi hoặc không chạy
    3. C.Trình cài đặt bị Windows hoặc macOS cảnh báo
    4. D.Tính năng không dùng được với engine đã chọn
    5. E.Routine không chạy theo lịch
  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ỏ.