Suparagent: đồng nghiệp AI tự host, bạn duyệt mới làm — 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à một không gian làm việc mã nguồn mở (Apache-2.0) để tạo các agent AI có tên, vai trò, trí nhớ và lịch chạy riêng, chạy trên máy bạn hoặc server của bạn. Bạn tự mang engine AI và tài khoản nhà cung cấp, vì repo không kèm mô hình. Bản desktop chạy từ mã nguồn bằng ba lệnh, cần Node.js 22+ và uv; README ghi rõ đây vẫn là giai đoạn thử nghiệm.
Suparagent là một không gian làm việc cho "đồng nghiệp AI": bạn tạo các agent có tên, giao cho mỗi agent một việc và một thư mục làm việc, rồi cho chúng phối hợp để hoàn thành 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ỗ. Bạn dùng bản desktop trên máy mình, hoặc tự dựng server riêng.
Repo này hợp với ai? Người làm văn phòng hay chủ cửa hàng nhỏ muốn có "trợ lý" làm việc lặp lại mỗi tuần (tóm tắt báo cáo, soạn bản tin nội bộ). Lập trình viên mới muốn thử mô hình nhiều agent phối hợp mà không bị khoá vào một nhà cung cấp. Điểm đáng giá nhất là hai thứ: dữ liệu ở lại máy hoặc server của bạn, và agent không tự làm điều quan trọng khi bạn chưa đồng ý.
Có một điều cần nói thẳng ngay từ đầu: Suparagent không kèm sẵn 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 mình. Hiện repo có khoảng 7.041 sao và 913 fork, nhưng chính tác giả ghi dự án đang phát triển tích cực và nhiều phần còn ở mức thử nghiệm. 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
Không gian làm việc mã nguồn mở để tạo đồng nghiệp AI có tên, trí nhớ, lịch chạy định kỳ và chỉ hành động khi bạn đồng ý.
I.Suparagent làm được gì
Dưới đây là các tính năng chính, giải thích theo lợi ích thực tế.
- 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 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. Trưởng nhóm hiện cần dùng Claude hoặc Codex. Lợi ích: bạn chia việc như chia cho người, thay vì nhét hết vào một cuộc chat dài.
- Giữ ngữ cảnh hữu ích. Agent có thể ghi chú, nhớ lại ghi chú và hội thoại cũ, tìm trong lịch sử. Bạn xem và sửa được những gì chúng nhớ. Lợi ích: không phải dặn lại từ đầu mỗi lần.
- Chạy việc theo lịch. Routine 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 duyệt; routine không bao giờ tự duyệt thay bạn. Lợi ích: việc lặp lại hằng tuần được làm sẵn, nhưng quyền quyết định vẫn ở 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 (chỉ 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 trong app.
- Kết nối công cụ và ứng dụng. Qua khoá Composio của riêng bạn, bạn nối GitHub, Gmail, Google Calendar rồi cấp quyền cho từng agent Claude hoặc Codex được chọn. Mọi thay đổi đều chờ bạn duyệt. Bạn cũng có thể thêm từng công cụ từ MCP Marketplace.
- Màn hình Today. Gom các 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 vào một chỗ. 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 hội thoại và các lần thử.
- Tái dùng chỉ dẫn. Lưu skill (chỉ dẫn bạn chọn cho một tin nhắn) và tạo agent từ mẫu.
- Dùng từ điện thoại. Ghép app điện thoại với server của bạn để chat, dừng một câu trả lời, cho phép hoặc từ chối một lần gọi công cụ, hoặc tạo và sửa agent. README ghi app này mới thử trên máy ảo Android và một điện thoại Android, chưa thử trên iOS, chưa có thông báo đẩy.
- 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 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ử.
Về engine, bạn có thể nối Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, một agent dòng lệnh khác dùng giao thức ACP, OpenRouter, hoặc API tương thích OpenAI như Ollama hay LM Studio. Không phải engine nào cũng hỗ trợ đủ tính năng; ví dụ nhập ảnh và máy tính riêng cho agent không có ở mọi engine.
II.Cần chuẩn bị gì
Theo README, để chạy bản desktop từ mã nguồn bạn cần:
- Node.js 22 trở lên.
- uv (công cụ quản lý Python, xem docs.astral.sh/uv).
- Ít nhất một engine trên cùng máy. Nếu dùng engine dòng lệnh (CLI), hãy cài và đăng nhập nó trước khi mở app. Nếu dùng engine qua API, bạn cấu hình trong Settings → Engines.
- Tài khoản nhà cung cấp AI của bạn. Suparagent không kèm mô hình hay gói đăng ký; dùng mô hình có thể tốn tiền.
- Docker: chỉ khi cần các máy tính cô lập (isolated agent computers) cho agent. Phần này là tuỳ chọn và còn thử nghiệm.
Nếu muốn tự host trên server, README ghi cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine. Bài này tập trung vào bản desktop vì đơn giản nhất. README không nêu yêu cầu RAM, ổ cứng hay GPU, nên mình không đoán.
Suparagent gửi cho engine bạn chọn câu hỏi 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 trong thư mục làm việc mà engine đọc. 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. Đừng trỏ agent vào thư mục chứa dữ liệu nhạy cảm nếu bạn chưa yên tâm về engine.
III.Cài đặt từng bước
- Chuẩn bịCài Node.js 22+, uv và một engine AI đã đăng nhập
- Tải mã nguồnDùng git clone để lấy repo về máy
- Vào thư mục desktopcd vào suparagent/desktop
- Chạy appGõ npm run app để mở ứng dụng
- Cấu hình lần đầuChọn engine, workspace và chế độ duyệt
- Tạo agent đầu tiênĐặt tên, giao việc, bắt đầu chat
A.Chuẩn bị Node.js, uv và engine
Cài Node.js bản 22 trở lên và uv theo hướng dẫn trên trang chính thức của chúng. Sau đó chuẩn bị một engine. Cách đơn giản nhất cho người mới là dùng một công cụ dòng lệnh bạn đã có (ví dụ Claude Code hoặc Codex CLI): cài nó, đăng nhập xong, rồi mới mở Suparagent. Nếu không dùng CLI, bạn sẽ nhập khoá API trong app ở bước cấu hình.
Chỗ người mới hay vấp: README yêu cầu engine phải sẵn sàng "trên cùng máy" với app. Cài engine ở máy khác thì app không thấy.
B.Tải mã nguồn về máy
Mở terminal (trên Windows là PowerShell hoặc Git Bash, trên macOS và Linux là Terminal), vào thư mục bạn muốn lưu dự án rồi chạy:
git clone https://github.com/Anil-matcha/suparagent.gitLệnh này tải toàn bộ repo vào một thư mục tên suparagent. Bạn cần cài Git trước nếu máy chưa có.
C.Vào thư mục desktop và chạy app
Đây là các lệnh đúng như README ghi:
git clone https://github.com/Anil-matcha/suparagent.git
cd suparagent/desktop
npm run appHai dòng sau là: cd suparagent/desktop đưa terminal vào thư mục bản desktop, và npm run app khởi động ứng dụng. Bạn phải chạy npm run app ngay trong thư mục desktop, nếu không npm sẽ báo không tìm thấy gì để chạy. README không ghi thêm lệnh cài phụ thuộc nào (như npm install) trước bước này. Nếu lệnh báo thiếu gói, hãy xem hướng dẫn thiết lập desktop trong thư mục docs của repo.
Trong thư mục gốc repo còn có tệp run-desktop.bat, nhưng README không giải thích cách dùng nó nên mình không khuyên gì thêm. Bạn có thể mở tệp đó ra đọc.
Về bản cài sẵn: README cho biết có trang Releases với installer desktop, nhưng installer còn thử nghiệm và chưa được ký số, nên Windows hay macOS có thể cảnh báo. README cũng nói cơ chế cập nhật chỉ đưa bạn một bộ cài đã kiểm tra SHA-256 để tự mở, không cài tự động, và đường cập nhật giữa các bản chưa được kiểm chứng từ đầu đến cuối.
D.Cấu hình lần chạy đầu
Lần đầu mở app, bạn chọn ba thứ: engine, workspace (thư mục làm việc) và chế độ duyệt. Sau đó:
- 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 để app dừng lại xin duyệt trước các hành động cần duyệt.
- Khi cần chia việc hoặc lặp lại việc, thêm đồng đội hoặc tạo routine.
Lời khuyên cho người mới: hãy bắt đầu với Ask first. Bạn sẽ thấy agent định làm gì trước khi nó làm.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh kiểm tra riêng, nên mình dựa vào các bước nó mô tả. Bạn coi như cài thành công khi:
- Sau
npm run app, cửa sổ ứng dụng mở ra và hiện màn hình thiết lập lần đầu (chọn engine, workspace, chế độ duyệt). - Trong Settings → Engines, engine bạn chọn hiện là đã sẵn sàng.
- Bạn tạo được một agent và gửi một tin nhắn, rồi nhận được câu trả lời từ engine.
Nếu cửa sổ không mở, hãy đọc thông báo lỗi trong terminal nơi bạn gõ lệnh. Nếu app mở nhưng engine không sẵn sàng, gần như chắc chắn là CLI chưa đăng nhập hoặc chưa cấu hình khoá API.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo những gì README mô tả. Mình dùng prompt tiếng Việt cho dễ hình dung; kết quả cụ thể còn tuỳ engine bạn dùng.
A.Bản tin 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, cuối tuần phải gom ghi chú và báo cáo rải rác trong một thư mục thành một bản tóm tắt gửi 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, ví dụ "Nghiên cứu viên" và "Biên tập viên". Cho cả ba cùng trỏ vào thư mục dự án, và đặt engine của trưởng nhóm là Claude hoặc Codex. Rồi nhắn cho trưởng nhóm:
Hãy lập bản tin tuần này từ các ghi chú và báo cáo trong thư mục dự án. Nhờ Nghiên cứu viên tổng hợp số liệu và rủi ro, nhờ Biên tập viên viết lại ngắn gọn, rồi gộp thành một bản dưới một trang.Kết quả: trưởng nhóm chia nhỏ việc, giao cho các agent chuyên môn chạy trong các cuộc hội thoại riêng, rồi nhận kết quả về để 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.
Việc nào lặp lại hằng tuần thì làm tay một lần cho chuẩn, rồi giao cho routine.
Ông T
B.Chủ shop biến việc lặp lại thành routine
Bối cảnh: bạn bán hàng online, mỗi sáng thứ Hai muốn có bản tóm tắt từ các tệp ghi chú đơn hàng và phản hồi khách mà bạn lưu trong một thư mục.
Cách làm: khi quy trình bản tin ở trên chạy ổn, tạo một routine chạy theo lịch hằng tuần với prompt tương tự, trỏ vào agent đó. Routine cũng có thể chạy bằng webhook hoặc bấm tay. Mỗi lần chạy xong, bạn xem kết quả và trả lời các yêu cầu duyệt, vì routine không tự duyệt thay bạn.
Lưu ý quan trọng: routine chạy trong backend, nên backend phải đang chạy. Nếu bạn tắt app hay tắt máy thì lịch không chạy. Với nhu cầu "luôn chạy", hãy xem hướng dẫn tự host trên server trong thư mục docs của repo.
C.Gom việc cần xử lý mỗi sáng với Today
Bối cảnh: bạn bận họp, hay quên việc đến hạn và các yêu cầu duyệt đang chờ.
Cách làm: mỗi sáng mở màn hình Today. Nó gom các yêu cầu duyệt, câu hỏi từ agent, kết quả routine, lỗi engine và công việc đến hạn. Nếu bạn nối Gmail và Google Calendar qua khoá Composio của mình, Today còn hiện thư và lịch ở chế độ chỉ đọc. Kết nối này chỉ dành cho agent Claude hoặc Codex, và mọi thay đổi đều chờ bạn duyệt.
Kết quả: một danh sách ngắn việc cần bạn quyết, thay vì phải mở từng cuộc chat. Cần nói thêm: README ghi phần ứng dụng kết nối mới được thử với một dịch vụ Composio giả, chưa phải dịch vụ thật, nên hãy dùng thận trọng.
D.Lập trình viên mới cho agent đọc thư mục dự án
Bối cảnh: bạn mới vào một dự án code và muốn một agent giúp hiểu cấu trúc mà không sợ nó sửa lung tung.
Cách làm: tạo agent với workspace là thư mục dự án, chọn chế độ Plan only (chỉ lập kế hoạch) hoặc Ask first. Rồi hỏi:
Đọc thư mục này và giải thích cấu trúc dự án cho người mới. Liệt kê các tệp quan trọng nhất và đề xuất thứ tự nên đọc. Chưa sửa gì cả.Kết quả: bạn nhận lời giải thích và kế hoạch, đồng thời xem lại được hoạt động công cụ cùng các quyết định duyệt trong app. Khi quen rồi, bạn mới nâng lên Accept edits cho những việc bạn tin tưởng.
VI.Lỗi hay gặp và cách xử lý
Gõ npm run app báo lỗi ngay. Thường do bạn đang đứng sai thư mục hoặc phiên bản Node thấp hơn 22. Kiểm tra bằng node --version, và chắc chắn bạn đã cd suparagent/desktop. Nếu vẫn lỗi, xem hướng dẫn thiết lập desktop trong thư mục docs và mở Issue trên trang GitHub của dự án kèm nội dung lỗi.
Không thấy engine nào sẵn sàng. Với engine CLI, README yêu cầu cài và đăng nhập trước khi mở app. Hãy đăng nhập CLI trong terminal, đóng app rồi mở lại. Với engine API, kiểm tra lại cấu hình trong Settings → Engines.
Windows hoặc macOS cảnh báo khi mở bản cài sẵn. README nói installer chưa được ký và mới kiểm chứng nền tảng ở mức hạn chế. Nếu không yên tâm, hãy chạy từ mã nguồn theo hướng dẫn trên, và chỉ tải installer từ trang Releases chính thức của repo.
Routine không chạy đúng giờ. Routine chạy trong backend, nên backend phải đang chạy. Máy ngủ hoặc app đã tắt thì lịch bỏ lỡ. Muốn chạy ổn định, cân nhắc tự host trên server.
Agent trưởng nhóm không giao việc được. README ghi tính năng giao việc theo nhóm còn mới và trưởng nhóm cần dùng Claude hoặc Codex. Nếu bạn đặt engine khác cho trưởng nhóm, hãy đổi lại.
Chi phí mô hình bất ngờ. Repo không kèm mô hình, mỗi lượt trả lời đều dùng tài khoản nhà cung cấp của bạn và có thể tính tiền. Hãy xem trang giá của nhà cung cấp, và thử việc nhỏ trước khi đặt routine chạy thường xuyên.
VII.Có nên dùng không
Điểm mạnh: mã nguồn mở (Apache-2.0), dữ liệu hội thoại, ghi chú và cài đặt nằm ở máy hoặc server của bạn; khoá API lưu qua Suparagent được mã hoá ở đó. Bạn chọn được nhiều loại engine, kể cả mô hình chạy nội bộ qua Ollama hay LM Studio. Cơ chế duyệt rõ ràng, routine không tự duyệt, và có nhiều chế độ từ Plan only đến Accept edits. Cách chia agent theo vai trò rất dễ hình dung với người làm văn phòng.
Giới hạn: README nói thẳng dự án đang phát triển, bản desktop và tự host đều ở mức thử nghiệm. Bản tự host 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ên không phải dịch vụ cho nhiều tổ chức. Giao việc theo nhóm còn mới. 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à tuỳ chọn thử nghiệm. App điện thoại chưa thử trên iOS. Một số phần như MCP Marketplace, máy tính đám mây và chuyển âm thanh thành chữ chưa qua kiểm chứng trên dịch vụ thật.
Cũng cần phân biệt: dịch vụ web trả phí trên trang chủ dự án là một sản phẩm riêng, do Suparagent vận hành, có gói riêng và chính sách dữ liệu riêng. Phần mã nguồn mở là bản desktop và bản tự host.
Khi nào nên chọn cách khác? Nếu bạn cần một công cụ ổn định để dùng cho việc quan trọng ngay hôm nay, hoặc cần dùng cho nhiều tổ chức, hoặc cần app iOS, thì nên chờ dự án chín hơn hoặc dùng giải pháp đã ổn định. Còn nếu bạn muốn học cách làm việc với nhiều agent, tự giữ dữ liệu và thử mô hình "đồng nghiệp AI" với việc không quá nhạy cảm, Suparagent là một lựa chọn đáng thử.
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 nên bạn tải và chạy được mà không phải trả tiền cho Suparagent. Tuy nhiên repo không kèm mô hình AI, bạn phải mang tài khoản nhà cung cấp của mình và việc dùng mô hình có thể tốn tiền. Dịch vụ web trên trang chủ là sản phẩm riêng có gói trả phí.
Cần GPU hoặc cấu hình máy mạnh không?
README không nêu yêu cầu GPU hay RAM. Nó chỉ yêu cầu Node.js 22 trở lên, uv và ít nhất một engine trên cùng máy. Nếu bạn dùng mô hình chạy nội bộ như Ollama thì cấu hình cần thêm tuỳ mô hình, nhưng tư liệu chưa nói cụ thể.
Suparagent chạy trên Windows được không?
Repo có bản desktop, installer cho các hệ điều hành trên trang Releases và một tệp run-desktop.bat. Tuy vậy README ghi installer còn thử nghiệm, chưa được ký số và việc kiểm chứng nền tảng còn hạn chế. Cách README hướng dẫn là chạy từ mã nguồn bằng git clone, cd suparagent/desktop rồi npm run app.
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ú agent, 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 bạn. 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 hỏi và ngữ cảnh cần thiết, nên 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 quyết định mức tự do: Ask first, Accept edits, Approve for me (cho Claude, Codex, Cursor) hoặc Plan only. Với routine, README nói rõ routine không bao giờ tự duyệt một hành động. Các thay đổi qua ứng dụng kết nối cũng chờ bạn duyệt.
Dùng được những mô hình AI nào?
README liệt kê Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent dòng lệnh dùng giao thức ACP, OpenRouter và API tương thích OpenAI như Ollama hay LM Studio. Tính năng sẵn có tuỳ engine; ví dụ trưởng nhóm cần dùng Claude hoặc Codex.
Tôi 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, dùng để chat, dừng câu trả lời, cho phép hoặc từ chối gọi công cụ và tạo hoặc sửa agent. README nói app mới thử trên máy ảo 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 có bản trên cửa hàng ứng dụng.


