Suparagent: đồng nghiệp AI tự host, có bộ nhớ và chờ bạn duyệt — 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à ứ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, bộ nhớ và lịch chạy. Bạn chạy trên máy mình hoặc tự dựng server, tự mang tài khoản mô hình AI. Cài bản desktop từ mã nguồn cần Node.js 22+ và uv; tác giả ghi rõ dự án cò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 cho mỗi agent một nhiệm vụ và một thư mục làm việc, rồi cho chúng cùng xử lý công việc thật. Hội thoại, bộ 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ể chạy bản desktop trên máy mình hoặc tự dựng server riêng.
Repo này dành cho người muốn dùng AI như một nhân viên phụ việc nhưng không muốn giao toàn quyền. Chủ shop, nhân viên văn phòng hay lập trình viên mới đều dùng được, miễn là bạn đã có sẵn một tài khoản AI. Điểm đáng giá nhất là cơ chế duyệt: agent chỉ hành động sau khi bạn đồng ý, và lịch chạy tự động không bao giờ tự duyệt thay bạn.
Có một lưu ý ngay từ đầu. Suparagent không kèm sẵn mô hình AI hay gói thuê bao nào. Bạn tự mang "động cơ" của 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 dự án đang phát triển tích cực và nhiều phần còn thử nghiệm. Hiện repo có khoảng 7041 sao và 913 fork. Bạn có thể xem video ngắn bên dưới để hình dung giao diện trước khi cài.
Anil-matcha/suparagent
Không gian làm việc mã nguồn mở để tạo các agent AI có tên, bộ nhớ, lịch chạy riêng và chỉ hành động sau khi bạn duyệt.
I.Suparagent làm được gì
Dưới đây là những tính năng chính, kèm lợi ích thực tế khi dùng.
- Tạo agent và đội nhóm. Mỗi agent có tên, vai trò, động cơ, thư mục làm việc, bộ nhớ và mức duyệt riêng. Bạn có thể đặt một agent "trưởng nhóm" chia việc cho các agent chuyên môn, hoặc cho nhiều agent trao đổi trong phòng chung. Trưởng nhóm hiện cần dùng Claude hoặc Codex.
- Giữ ngữ cảnh. Agent có thể ghi chú, nhớ lại ghi chú và hội thoại cũ, 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 đỡ phải giải thích lại từ đầu mỗi lần.
- Chạy việc theo lịch (routine). Một routine có thể chạy theo lịch, qua webhook hoặc bấm chạy tay. Bạn xem kết quả từng lần chạy và trả lời các yêu cầu 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 (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). 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. Bạn 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. Mọi thay đổi vẫn chờ bạn duyệt. Ngoài ra có thể thêm từng công cụ từ MCP Marketplace.
- Màn hình Today. Gom các việc cần chú ý: yêu cầu duyệt, câu hỏi, kết quả routine, lỗi động cơ, việc đến hạn. Nó có thể hiện 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ử.
- Dùng lại hướng 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 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 thử trên 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 để chuyển thành chữ (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 tải về, và bạn cần:
- Node.js 22 trở lên.
- uv (công cụ quản lý Python, có hướng dẫn trên trang của uv).
- Ít nhất một động cơ AI có sẵn trên cùng máy. Nếu dùng động cơ dạng dòng lệnh (CLI), hãy cài và đăng nhập nó trước khi mở app. Nếu dùng 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 (tính năng tuỳ chọn).
Danh sách động cơ README nêu: 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 động cơ nào cũng hỗ trợ ảnh hay máy tính cô lập.
Còn nếu muốn tự dựng server: README ghi cần máy chủ Linux, HTTPS, Docker (hoặc Node.js và uv) và một động cơ. README chưa ghi lệnh cụ thể ở phần tóm tắt này. Bạn xem hướng dẫn Self-hosting trong thư mục docs/ của repo.
Suparagent không kèm mô hình AI. Mỗi lượt trả lời, động cơ bạn chọn nhận câu hỏi 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à nó đọc). Nếu động cơ là dịch vụ trên mạng, dữ liệu đó theo điều khoản của nhà cung cấp, và việc dùng mô hình có thể mất tiền. Hãy kiểm tra gói cước của bạn trước.
III.Cài đặt từng bước
- Chuẩn bị công cụCài Node.js 22+ và uv, cài và đăng nhập một động cơ AI
- Tải mã nguồnDùng git clone để lấy repo về máy
- Chạy ứng dụngVào thư mục desktop và chạy npm run app
- Cấu hình lần đầuChọn động cơ, thư mục làm việc, chế độ duyệt
- Tạo agent đầu tiênĐặt tên, nhiệm vụ, thư mục rồi bắt đầu chat
A.Chuẩn bị công cụ
Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) và kiểm tra bạn đã có Node.js 22 trở lên cùng uv. Nếu dùng động cơ CLI như Claude Code hay Codex, hãy đăng nhập nó trong terminal trước. App sẽ dùng chính phiên đăng nhập đó trên máy bạn. README chưa ghi lệnh kiểm tra phiên bản, nên bạn xem tài liệu cài đặt của Node.js và uv ở trang chủ của chúng.
B.Tải mã nguồn
Lệnh dưới tải repo về một thư mục mới tên suparagent. Bạn cần cài Git trước. Hãy chạy lệnh ở nơi bạn muốn đặt thư mục, ví dụ thư mục Documents.
git clone https://github.com/Anil-matcha/suparagent.gitC.Chạy ứng dụng
Vào thư mục desktop bên trong repo rồi chạy app. Chỗ người mới hay vấp: phải đứng đúng trong thư mục desktop, không phải thư mục gốc.
cd suparagent/desktop
npm run appREADME chỉ ghi hai lệnh này cho bản desktop từ mã nguồn. Nếu terminal báo thiếu gói, hãy xem hướng dẫn desktop trong thư mục docs/ của repo, đừng tự đoán lệnh.
D.Cấu hình lần đầu
Lần đầu mở app, bạn chọn ba thứ: động cơ, thư mục làm việc (workspace) và chế độ duyệt. Nếu chưa chắc, hãy chọn Ask first: app sẽ dừng lại hỏi bạn trước những hành động cần duyệt. Sau đó vào Settings → Engines để chắc chắn có ít nhất một động cơ ở trạng thái sẵn sàng.
E.Tạo agent đầu tiên
Tạo một agent với tên, một nhiệm vụ viết rõ ràng và một thư mục làm việc. Rồi mở chat và thử một việc nhỏ. Khi muốn chia việc hay lặp lại việc, bạn thêm đồng đội hoặc tạo routine.
README còn nhắc: có bộ cài desktop ở trang Releases của repo, nhưng chúng ở mức thử nghiệm và chưa ký số. Luồng cập nhật có kiểm tra SHA-256 và để bạn tự mở bộ cài, không tự cài. Con đường cập nhật giữa các bản chưa được kiểm chứng đầy đủ.
IV.Kiểm tra đã chạy được chưa
Theo tư liệu, dấu hiệu thành công là cửa sổ ứng dụng mở ra và hỏi bạn chọn động cơ, thư mục làm việc và chế độ duyệt. Sau đó:
- Vào Settings → Engines và thấy ít nhất một động cơ báo sẵn sàng.
- Tạo được một agent và gửi một tin nhắn thử, ví dụ "Chào bạn, hãy liệt kê các tệp trong thư mục làm việc".
- Nếu để chế độ Ask first, bạn thấy app hiện yêu cầu duyệt trước khi agent làm việc cần quyền.
Nếu động cơ chưa sẵn sàng, thường là do CLI chưa đăng nhập hoặc chưa cấu hình API. Xem phần lỗi bên dưới.
V.Dùng vào việc thật
Dưới đây là các tình huống bám theo khả năng có trong README.
A.Chủ shop cần bản tóm tắt tuần
Bạn có thư mục chứa ghi chú, báo cáo doanh số và phản hồi khách của tuần. Hãy tạo một agent trưởng nhóm (động cơ Claude hoặc Codex), thêm hai agent chuyên môn: một "người nghiên cứu" và một "người biên tập", rồi cho cả ba cùng thư mục làm việc. Gửi cho trưởng nhóm một câu như:
Hãy lập bản tóm tắt tuần từ các ghi chú và báo cáo trong thư mục này: doanh số, phản hồi khách, việc cần làm tuần sau.Trưởng nhóm chia nhỏ yêu cầu, giao cho hai agent kia xử lý trong các cuộc hội thoại riêng, rồi tổng hợp lại. Bạn theo dõi trong chat và duyệt hành động khi cài đặt yêu cầu. Kết quả là một bản tóm tắt tổng hợp mà bạn chỉnh sửa trước khi dùng.
Agent làm nhanh, nhưng người bấm "đồng ý" vẫn là bạn.
Ông T
B.Nhân viên văn phòng muốn lặp lại việc mỗi tuần
Sau khi quy trình ở trên chạy ổn, bạn biến nó thành routine chạy hằng tuần. Routine chạy ở phần backend nên backend phải luôn bật. Mỗi lần chạy, kết quả hiện trong app và bạn trả lời các yêu cầu duyệt. Màn hình Today gom kết quả routine, câu hỏi và lỗi để bạn xử lý một lượt, thay vì phải mở từng hội thoại.
C.Dùng bộ nhớ để khỏi giải thích lại
Bạn làm việc với một agent "trợ lý nội dung" nhiều ngày. Hãy dặn nó các quy tắc cố định, ví dụ giọng văn của thương hiệu, và để nó ghi chú. Lần sau, agent tìm lại ghi chú và hội thoại cũ liên quan. Bạn có thể mở phần bộ nhớ để đọc và sửa những gì nó đang nhớ. Kết quả là ít phải lặp lại yêu cầu, và nếu nó nhớ sai thì bạn sửa được.
D.Lập trình viên mới: agent có nhiều mức quyền
Bạn muốn thử cho agent sửa tệp trong một thư mục dự án thử nghiệm. Hãy bắt đầu với chế độ Plan only để agent chỉ lập kế hoạch, rồi chuyển sang Ask first hoặc Accept edits khi đã tin tưởng. Mọi hoạt động công cụ và quyết định duyệt đều xem lại được trong app. Nếu cần kết nối GitHub hay Gmail, bạn thêm khoá Composio của riêng mình và chỉ cấp quyền cho agent cần dùng.
VI.Lỗi hay gặp và cách xử lý
Động cơ báo chưa sẵn sàng. Thường là CLI chưa cài, chưa đăng nhập, hoặc API chưa điền khoá. Hãy cài và đăng nhập động cơ trong terminal trước khi mở app, hoặc điền thông tin ở Settings → Engines. Khoá API lưu qua Suparagent được mã hoá trên máy bạn.
Lệnh npm run app báo lỗi hoặc không tìm thấy. Kiểm tra bạn đang đứng trong thư mục suparagent/desktop và Node.js là bản 22 trở lên. Nếu vẫn lỗi, xem tài liệu desktop trong docs/ hoặc hỏi ở mục Issues của repo, thay vì chạy lệnh lạ tìm được trên mạng.
Agent không dùng được ứng dụng đã kết nối hay tính năng đặc biệt. Ứng dụng kết nối chỉ dùng được với agent Claude và Codex. Trưởng nhóm cũng cần Claude hoặc Codex. Một số động cơ không hỗ trợ ảnh hoặc máy tính cô lập. Hãy xem bảng khả năng từng động cơ trong tài liệu của repo.
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 app hay server thì lịch sẽ không chạy.
Windows hoặc hệ điều hành cảnh báo khi mở bộ cài. README ghi bộ cài desktop cò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 ngại thì chạy từ mã nguồn như hướng dẫn ở trên.
VII.Có nên dùng không
Điểm mạnh. Bạn giữ quyền kiểm soát: có nhiều chế độ duyệt, routine không tự duyệt, dữ liệu hội thoại và ghi chú lưu trên máy hoặc server của bạn. Bạn chọn động cơ tuỳ ý, từ dịch vụ trên mạng đến mô hình chạy cục bộ như Ollama hay LM Studio. Giấy phép Apache-2.0 và mã nguồn mở nên dễ kiểm tra.
Giới hạn. Tác giả nói thẳng dự án còn sớm và đang thay đổi. Server tự host ở mức thử nghiệm, chỉ có một chủ sở hữu và có thể mời đồng đội, mọi người dùng chung agent, hội thoại và bộ nhớ. Giao việc cho đội agent còn mới. App điện thoại chưa thử trên iOS, chưa có thông báo đẩy. Docker computers, công cụ trình duyệt và bản macOS gốc còn thử nghiệm. Kết nối ứng dụng qua Composio mới được thử trên dịch vụ giả lập, chưa phải dịch vụ thật. Một số phần như MCP Marketplace, âm thanh chưa qua kiểm chứng thực tế.
Khi nào chọn cách khác. Nếu bạn cần công cụ ổn định, đã đóng gói sẵn và có hỗ trợ chính thức cho việc quan trọng, hãy cân nhắc lựa chọn khác hoặc thử Suparagent ở việc không quan trọng trước. Nếu bạn không có sẵn tài khoản hay API của một động cơ AI thì chưa dùng được, vì repo không kèm mô hình. Bản web có tính phí (Starter 15 USD, Standard 49 USD, Pro 99 USD mỗi tháng theo README) là sản phẩm riêng, tách khỏi phần mã nguồn mở bạn tự chạy.
Lời khuyên của mình: cứ cài bản desktop, chọn Ask first, giao một việc nhỏ trong thư mục thử nghiệm và xem agent làm ra sao trước khi giao việc lớn hơn.
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à server tự host) dùng giấy phép Apache-2.0 và tải về chạy được. Nhưng repo không kèm mô hình AI, bạn tự mang tài khoản, CLI đăng nhập hoặc khoá API, và việc dùng mô hình có thể tốn tiền. Bản web trả phí là sản phẩm riêng, với gói Starter 15 USD, Standard 49 USD, Pro 99 USD mỗi tháng theo README.
Có cần GPU không?
Tư liệu không nói cần GPU. Suparagent dùng động cơ bạn chọn như Claude Code, Codex, Gemini CLI, OpenRouter hay API tương thích OpenAI. Nếu bạn dùng mô hình chạy cục bộ như Ollama hoặc LM Studio thì phần cứng phụ thuộc vào mô hình đó; repo chưa nêu yêu cầu cụ thể.
Chạy trên Windows được không?
Repo có file run-desktop.bat và README nói bộ cài desktop có sẵn ở trang Releases, nhưng tác giả ghi bộ cài còn thử nghiệm, chưa ký số và mới kiểm chứng nền tảng hạn chế. Tư liệu chưa nêu rõ mức hỗ trợ Windows, nên bạn xem tài liệu desktop trong thư mục docs.
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 và 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, mỗi lượt trả lời, động cơ bạn chọn nhận câu hỏi và ngữ cảnh cần thiết. Nếu động cơ là dịch vụ trên mạng, dữ liệu đó theo điều khoản của nhà cung cấp.
Agent có tự ý làm việc khi tôi không biết không?
Bạn chọn mức tự do: Ask first, Accept edits, Approve for me hoặc Plan only. Routine chạy theo lịch nhưng không bao giờ tự duyệt một hành động, bạn vẫn phải trả lời các yêu cầu duyệt. Chế độ Approve for me chỉ dành cho Claude, Codex và Cursor.
Muốn tự dựng server thì làm thế nào?
README chỉ nêu yêu cầu: máy chủ Linux, HTTPS, Docker hoặc Node.js và uv, cùng một động cơ. Phần này còn thử nghiệm và có một chủ sở hữu. README chưa ghi lệnh cụ thể ở phần tóm tắt, bạn xem hướng dẫn Self-hosting trong thư mục docs của repo.
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: 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 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.


