Suparagent: đồng nghiệp AI có trí nhớ, lịch chạy và bước 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' có tên, vai trò, trí nhớ và lịch chạy riêng. Bạn chạy nó trên máy mình hoặc tự dựng máy chủ, rồi nối với công cụ AI đã có như Claude Code, Codex hay Ollama. Cài bản desktop từ mã nguồn cần Node.js 22+ và uv, mức độ vừa phải; dự án còn ở giai đoạ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 từng agent có tên riêng, 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 làm việc thật. Trò chuyện, trí nhớ, lịch chạy định kỳ và các lần xin duyệt đều nằm chung một chỗ. 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.000 sao và hơn 900 fork trên GitHub.
Repo này hợp với ba nhóm người. Nhóm thứ nhất là người làm văn phòng, kinh doanh muốn có trợ lý AI lặp lại một việc mỗi tuần, ví dụ gom báo cáo thành bản tóm tắt. Nhóm thứ hai là lập trình viên muốn một giao diện chung để điều phối nhiều agent. Nhóm thứ ba là người không muốn đưa dữ liệu lên dịch vụ của bên khác, nên chọn chạy trên máy mình. Suparagent không kèm sẵn mô hình AI nào. Bạn mang theo công cụ AI hoặc tài khoản mà mình đã có.
Điểm đáng giá nhất là cơ chế duyệt. Bạn chọn mức tự do cho agent, và với chế độ hỏi trước thì agent phải dừng lại chờ bạn đồng ý rồi mới làm việc cần quyền. Ngay cả routine chạy theo lịch cũng không tự duyệt hành động thay bạn. 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
Suparagent là không gian làm việc mã nguồn mở để tạo các agent AI có tên, có trí nhớ, chạy theo lịch và chỉ hành động khi bạn đồng ý.
I.Suparagent làm được gì
- Tạo agent và nhóm agent. Mỗi agent có tên, vai trò, engine (công cụ AI đứng sau), thư mục làm việc, trí nhớ và thiết lập 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 cho nhiều agent cùng làm trong một 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 thật, thay vì nhồi mọi thứ vào một cuộc trò chuyện dài.
- Giữ ngữ cảnh. Agent có thể ghi chú, nhớ lại ghi chú và hội thoại cũ, tìm lại trong lịch sử. Bạn xem và sửa được những gì agent nhớ. Nhờ vậy bạn không phải giải thích lại bối cảnh dự án mỗi lần.
- Chạy việc theo lịch (routine). Routine chạy theo giờ, theo webhook hoặc bấm 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. Hợp với việc lặp lại như báo cáo hằng tuần.
- Chọn mức tự do cho agent. Có bốn chế độ: Ask first (hỏi trước), Accept edits (tự 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 được hoạt động công cụ và các quyết định duyệt trong ứng dụng.
- Nối công cụ và ứng dụng. Qua khoá Composio của chính bạn, có thể 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 vẫn chờ bạn duyệt. Ngoài ra có MCP Marketplace để thêm từng công cụ riêng lẻ.
- Màn hình Today. Gom phê duyệt, câu hỏi, kết quả routine, lỗi engine và việc đến hạn vào một chỗ. Có thể hiện thêm thư Gmail và lịch ở chế độ chỉ đọc.
- Bả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. 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.
- 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ụ, tạo và sửa agent. README nói rõ app này mới thử trên Android, chưa thử trên iOS.
- Làm việc với file. Tìm trong 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 file trong thư mục làm việc, xuất lịch sử.
Về engine, README liệt kê: Claude Code, 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 tuỳ engine; ví dụ không phải engine nào cũng nhận ảnh hay dùng được máy tính của agent.
II.Cần chuẩn bị gì
Theo README, bản desktop chạy từ mã nguồn tải về, và cần:
- Node.js 22 trở lên.
- uv (công cụ quản lý Python, trang chủ 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, bạn cài nó và đăng nhập xong trước khi mở Suparagent. Nếu dùng engine qua API, bạn cấu hình trong Settings → Engines.
- Docker chỉ cần nếu muốn dùng máy tính cô lập cho agent (tính năng tuỳ chọn, còn thử nghiệm).
- 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ý mô hình, nên chi phí dùng mô hình do bạn trả cho nhà cung cấp.
Nếu muốn tự dựng máy chủ, README ghi cần máy chủ Linux, HTTPS, Docker hoặc Node.js và uv, cùng một engine. Phần này ở mức thử nghiệm, và bài này tập trung vào bản desktop. Hệ điều hành cho bản desktop, README không nêu cụ thể, chỉ nói bộ cài chưa ký và mới kiểm chứng trên một số nền tảng.
Suparagent còn ở giai đoạn phát triển, bộ cài desktop chưa được ký. Bạn tự chịu trách nhiệm khi cho agent đọc thư mục. Hãy bắt đầu với một thư mục thử nghiệm, để chế độ Ask first, và đừng cho agent truy cập thư mục chứa dữ liệu quan trọng khi chưa quen.
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 engine (ví dụ Claude Code)
- 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 ứng dụngGõ npm run app và làm theo màn hình lần đầu
- Kiểm tra engineMở Settings → Engines xem engine đã sẵn sàng chưa
A.Chuẩn bị Node.js, uv và engine
README không đưa lệnh cài từng công cụ này, nên bạn cài theo trang chủ của chúng. Sau khi cài, bạn có thể kiểm tra Node.js bằng lệnh phổ thông sau (cần ra số phiên bản từ 22 trở lên):
node --versionVới engine dạng dòng lệnh như Claude Code hay Codex CLI, hãy cài xong và đăng nhập trước. Chỗ người mới hay vấp là mở Suparagent trước rồi mới đăng nhập engine, khiến ứng dụng báo engine chưa sẵn sàng.
B.Tải mã nguồn về máy
Mở terminal (trên Windows là PowerShell hoặc Git Bash), chuyển tới thư mục bạn muốn đặt dự án rồi chạy:
git clone https://github.com/Anil-matcha/suparagent.gitLệnh này tạo thư mục suparagent ngay trong nơi bạn đang đứng. Cần cài Git từ trước.
C.Vào thư mục desktop và chạy
Đúng như README, bạn vào thư mục desktop rồi chạy lệnh khởi động:
cd suparagent/desktop
npm run appLần đầu chạy có thể mất thời gian. README không mô tả chi tiết quá trình này, nên nếu thấy lỗi, hãy đọc kỹ dòng báo lỗi cuối cùng trong terminal. Đừng đóng cửa sổ terminal khi ứng dụng đang chạy.
Trong thư mục gốc repo còn có file run-desktop.bat, nhưng phần Quick start của README không nhắc tới nó. Nếu muốn dùng, hãy mở ra đọc xem nó làm gì trước khi chạy. Repo cũng có Dockerfile và compose.yaml cho cách chạy bằng Docker, còn README chưa ghi lệnh cụ thể. Bạn xem mục Self-hosting trong thư mục docs/ của repo.
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 (workspace) và chế độ duyệt. Sau đó README gợi ý:
- Vào Settings → Engines và xác nhận có một engine báo sẵn sàng.
- 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.
- Bắt đầu chat. Chọn Ask first để agent dừng chờ bạn duyệt trước các hành động cần quyền.
- Khi cần, thêm đồng đội hoặc tạo routine để chia việc hay lặp lại việc.
Nếu không muốn build từ mã nguồn, README có nhắc trang Releases với các bộ cài desktop. Tuy nhiên chúng đang ở mức thử nghiệm và chưa ký, nên Windows hoặc macOS có thể cảnh báo khi mở. Tính năng cập nhật có hỗ trợ chỉ đưa bộ cài đã kiểm SHA-256 để bạn tự mở, không tự cài.
IV.Kiểm tra đã chạy được chưa
Theo README, bạn biết mình cài đúng khi:
- Cửa sổ ứng dụng mở ra sau
npm run appvà cho bạn chọn engine, workspace, chế độ duyệt. - Trong Settings → Engines, ít nhất một engine hiện trạng thái sẵn sàng.
- Bạn tạo được một agent, mở chat, gửi một câu và nhận được trả lời. Với chế độ Ask first, khi agent định làm việc cần quyền thì ứng dụng hiện yêu cầu duyệt để bạn đồng ý hoặc từ chối.
Cách thử an toàn: tạo agent trỏ vào một thư mục chỉ có vài file ghi chú, rồi nhờ nó liệt kê và tóm tắt những file đó. Nếu nó trả lời được và hỏi bạn khi cần đụng tới file, mọi thứ đang chạy tốt.
V.Dùng vào việc thật
A.Bản tóm tắt dự án mỗi tuần cho người quản lý
Bạn quản lý một dự án, mỗi tuần phải gom các ghi chú và báo cáo rải rác thành một bản tóm tắt. Đây chính là ví dụ trong README. Bạn tạo một agent trưởng nhóm, chọn engine là Claude hoặc Codex, cùng 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. Sau đó nhắn cho trưởng nhóm, ví dụ:
Hãy lập 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. Giao người nghiên cứu gom ý chính, người biên tập viết lại gọn.Trưởng nhóm chia nhỏ yêu cầu và giao cho hai agent kia. Mỗi agent làm trong một cuộc trò chuyện riêng, rồi kết quả trả về cho trưởng nhóm tổng hợp. Bạn theo dõi trong chat và duyệt khi cần. Khi quy trình đã ổn, bạn biến nó thành routine chạy hằng tuần và xem lại từng lần chạy.
Agent chỉ làm việc thật sau khi bạn bấm đồng ý.
Ông T
B.Chủ shop nhỏ giữ ghi chú khách hàng và việc cần làm
Bạn bán hàng online và hay quên ai hỏi gì, đơn nào cần gọi lại. Tạo một agent tên "Trợ lý đơn hàng" với thư mục chứa file ghi chú khách. Bạn dặn nó ghi nhớ các điều khách yêu cầu. Lần sau, bạn hỏi nó nhớ lại khách đã hỏi gì, và vì agent lưu ghi chú, bạn không cần kể lại từ đầu. Bạn có thể mở phần trí nhớ để đọc và sửa những gì nó lưu, nên không sợ nó nhớ sai mà không biết. Dùng màn hình Today để xem việc đến hạn và yêu cầu đang chờ bạn trả lời.
C.Nhân viên văn phòng theo dõi việc bằng bảng việc và lịch
Bạn là nhân viên hành chính, mỗi sáng thứ Hai cần soạn danh sách việc tuần này. Bạn dùng bảng việc để giao việc cho các agent, hẹn chạy một lần vào giờ cần, và xem lại các lần thử khi kết quả chưa ưng. Nếu đã nối Gmail và Google Calendar qua khoá Composio của bạn, màn hình Today có thể hiện thư và lịch ở chế độ chỉ đọc để bạn nhìn tổng quan. Lưu ý: README nói kết nối ứng dụng mới được thử với một dịch vụ Composio giả lập, chưa phải dịch vụ thật, nên hãy thử cẩn thận.
D.Lập trình viên dùng chung một giao diện cho nhiều engine
Bạn đã có Claude Code, Codex và một mô hình chạy cục bộ qua Ollama. Thay vì mở ba công cụ rời, bạn tạo các agent mỗi cái dùng một engine khác nhau, đặt trong cùng workspace, đặt chế độ Plan only cho agent chỉ cần đưa kế hoạch. Với việc lặp lại như rà soát một thư mục mỗi tối, bạn tạo routine chạy theo lịch hoặc theo webhook. Routine chạy ở backend nên backend phải luôn bật.
VI.Lỗi hay gặp và cách xử lý
A.Ứng dụng báo chưa có engine sẵn sàng
Nguyên nhân thường gặp là chưa cài engine hoặc chưa đăng nhập. README dặn cài và đăng nhập engine dòng lệnh trước khi mở Suparagent. Hãy đăng nhập engine ngoài terminal, rồi vào Settings → Engines kiểm tra lại. Nếu dùng engine qua API, kiểm tra khoá đã điền đúng chỗ chưa.
B.Lệnh npm run app không chạy hoặc báo thiếu thứ gì đó
Trước hết kiểm tra bạn đang đứng đúng thư mục suparagent/desktop (lỗi này rất hay gặp khi quên lệnh cd). Sau đó chạy node --version để chắc chắn là Node.js 22 trở lên, và kiểm tra uv đã cài. README chưa liệt kê chi tiết các bước khác nên nếu lỗi vẫn còn, hãy xem thư mục docs/ trong repo, mục desktop setup, hoặc hỏi ở Discord và GitHub Issues của dự án.
C.Tính năng agent computer hoặc Docker không hoạt động
Máy tính cô lập cho agent cần Docker và README ghi đây là tính năng thử nghiệm, tuỳ chọn. Nếu bạn chưa cài hoặc chưa bật Docker, hãy cài Docker trước. Không phải engine nào cũng hỗ trợ tính năng này. Nếu bạn chưa cần, cứ bỏ qua để dùng phần chat, trí nhớ và routine.
D.Routine không chạy đúng giờ
Routine chạy trong backend nên nếu bạn tắt ứng dụng hoặc backend thì lịch sẽ không chạy. Hãy để nó chạy liên tục, hoặc dùng máy chủ riêng cho việc cần chạy đều. Ngoài ra, routine không bao giờ tự duyệt hành động: nếu trong lần chạy có việc cần quyền, nó sẽ chờ bạn trả lời.
E.Windows hoặc macOS cảnh báo khi mở bộ cài
Bộ cài desktop trong Releases là bản thử nghiệm và chưa ký, nên hệ điều hành có thể cảnh báo. Đây là hành vi dự kiến, không phải lỗi của máy bạn. Chỉ tải bộ cài từ trang Releases chính thức của dự án, và nếu không yên tâm, chạy từ mã nguồn như ở trên.
VII.Có nên dùng không
Điểm mạnh. Bạn giữ dữ liệu trên máy mình: với desktop và tự dựng máy chủ, 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 chính nó, còn file 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ỳ ý, từ Claude Code đến mô hình chạy cục bộ. Cơ chế duyệt rõ ràng, và agent có trí nhớ, lịch chạy, nhóm làm việc trong một giao diện thống nhất.
Giới hạn. README tự nói dự án còn sớm và đang thay đổi. Máy chủ tự dựng ở mức thử nghiệm, một người làm chủ và mời đồng đội vào dùng chung. Ứng dụng điện thoại chưa thử trên iOS, không có thông báo đẩy. Tính năng giao việc trong nhóm còn mới và trưởng nhóm phải dùng Claude hoặc Codex. Máy tính Docker, công cụ trình duyệt và bản macOS gốc đều là thử nghiệm. Kết nối ứng dụng qua Composio, MCP Marketplace, máy tính đám mây và chuyển giọng nói thành chữ chưa được kiểm chứng đầy đủ.
Một điều cần nhớ về quyền riêng tư. Khi agent trả lời, engine bạn chọn nhận câu hỏi và ngữ cảnh của lượt đó, có thể gồm văn bản bạn đính kèm, ghi chú liên quan và nội dung file nó đọc. Nếu engine là dịch vụ trên mạng, dữ liệu đó theo điều khoản của nhà cung cấp. Muốn giữ kín hoàn toàn, hãy chọn engine chạy cục bộ.
Khi nào chọn cách khác. Nếu bạn chỉ cần hỏi đáp thỉnh thoảng thì app chat thông thường đơn giản hơn. Nếu cần một hệ thống ổn định cho nhiều tổ chức, README nói rõ bản tự dựng không phải dịch vụ nhiều tổ chức. Ngoài ra còn có bản web do chính dự án vận hành, là sản phẩm riêng với gói trả phí, bạn xem trang giá của họ nếu muốn thử. Với việc quan trọng, hãy bắt đầu nhỏ, giữ chế độ hỏi trước và đọc kỹ mục Known limitations trong README.
Câu hỏi thường gặp
Suparagent có miễn phí không?
Phần mã nguồn mở dùng giấy phép Apache-2.0 và bạn tự chạy trên máy hoặc máy chủ của mình. Tuy nhiên Suparagent không kèm mô hình AI, nên bạn vẫn phải trả tiền cho nhà cung cấp mô hình nếu dùng dịch vụ có tính phí. Bản web do dự án vận hành là sản phẩm riêng, có gói miễn phí để xem thử và các gói trả phí.
Cần GPU hoặc cấu hình mạnh không?
Tư liệu không nêu yêu cầu GPU hay cấu hình phần cứng cho bản desktop. Điều README yêu cầu là Node.js 22+, uv và một engine. Nếu bạn dùng mô hình chạy cục bộ như Ollama thì máy phải đủ sức chạy mô hình đó, phần này phụ thuộc mô hình bạn chọn.
Chạy được trên Windows không?
Repo có file run-desktop.bat ở thư mục gốc, nhưng README không giải thích chi tiết. README chỉ nói bộ cài desktop là thử nghiệm, chưa ký và mới được kiểm chứng trên số nền tảng hạn chế. Vì vậy bạn nên thử trên máy không chứa dữ liệu quan trọng trước và xem tài liệu desktop setup trong thư mục docs.
Dữ liệu của tôi có an toàn không?
Với desktop và tự dựng máy chủ, hội thoại, ghi chú, routine và cài đặt lưu trong dữ liệu của chính bản cài đó, và khoá API lưu qua Suparagent được mã hoá. Tuy vậy engine bạn chọn vẫn nhận câu hỏi và ngữ cảnh của mỗi lượt, nên nếu engine là dịch vụ trên mạng thì dữ liệu đó thuộc điều khoản của nhà cung cấp. Dự án cũng còn đang phát triển nên hãy thận trọng với dữ liệu quan trọng.
Suparagent dùng được với những mô hình 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 hay LM Studio. Công cụ khả dụng tuỳ engine, ví dụ không phải engine nào cũng nhận ảnh hoặc dùng được máy tính của agent.
Agent có tự làm bậy khi tôi không để ý không?
Bạn chọn mức tự do cho từng agent: Ask first, Accept edits, Approve for me hoặc Plan only. Với Ask first, agent dừng chờ bạn duyệt trước các hành động cần quyền. Routine chạy theo lịch cũng không bao giờ tự duyệt hành động, nó chờ bạn trả lời.
Có dùng được từ điện thoại không?
Có ứng dụng điện thoại ghép 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 lệnh gọi công cụ, tạo và sửa agent. README ghi rõ app mới thử trên máy 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 có bản trên cửa hàng ứng dụng.


