Suparagent: đồng nghiệp AI có tên, có trí nhớ, 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ở (Apache-2.0, viết bằng Python) để tạo các agent AI có tên, vai trò, bộ nhớ và lịch chạy riêng, chạy trên máy bạn hoặc server tự host. Bạn tự mang engine AI và tài khoản của 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, nhưng cần Node.js 22 trở lên và uv, nên người mới sẽ mất một chút thời gian chuẩn bị.
Suparagent là một không gian làm việc mã nguồn mở cho "đồng nghiệp AI". Bạn tạo các 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. Hội thoại, trí nhớ, lịch chạy định kỳ và các lần xin duyệt đều nằm trong một chỗ. Hiện repo có khoảng 7041 sao và 913 fork trên GitHub.
Repo này hợp với ai? Nó hợp với người muốn có một "nhân viên AI" làm việc đều đặn mà vẫn nắm quyền quyết định. Ví dụ: chủ shop muốn có bản tổng hợp hằng tuần, nhân viên văn phòng cần soạn báo cáo từ một đống ghi chú, hoặc lập trình viên muốn nhiều agent chia nhau việc. Điểm đáng giá nhất là cơ chế duyệt: bạn chọn mức tự do cho agent, và routine (việc chạy theo lịch) không bao giờ tự phê duyệt thay bạn.
Có một điều cần nói rõ ngay: Suparagent không kèm mô hình AI hay gói đăng ký nào. Bạn mang theo engine và tài khoản của riêng bạn, ví dụ Claude Code, Codex CLI hay một API tương thích OpenAI. Dự án cũng đang phát triển tích cực, nên nhiều phần còn ở mức thử nghiệm. 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
Suparagent là không gian làm việc mã nguồn mở cho các đồng nghiệp 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ì
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à nhóm agent. Mỗi agent có tên, vai trò, engine, thư mục làm việc, bộ nhớ và cài đặt phê 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 các "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 mọi thứ vào một cuộc chat dài.
- 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ì chúng nhớ, nên không sợ agent nhớ sai mà bạn không biết.
- Chạy việc theo lịch. Routine có thể 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 phê duyệt. Việc lặp lại hằng tuần không cần bạn nhắc lại từ đầu.
- 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 được 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 kết 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 đều chờ bạn duyệt. Ngoài ra bạn có thể thêm từng công cụ từ MCP Marketplace.
- Xem gì cần bạn xử lý. 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à việc đến hạn. Nó còn hiện được thư và lịch ở chế độ chỉ đọc.
- Lên kế hoạch và theo dõi. Có bảng công việc và lịch để giao việc, đặt lịch 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. Bạn lưu skill (các 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ụ, tạo và sửa agent.
- Làm việc với tệp và lịch sử. Bạn 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 tệp trong thư mục làm việc, và xuất lịch sử.
II.Cần chuẩn bị gì
Theo README, bản desktop chạy từ mã nguồn. Bạn 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 để 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 và đăng nhập engine đó trước khi mở ứng dụng. Nếu dùng engine qua 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, và phần này là tuỳ chọn.
- Git để tải mã nguồn về (lệnh git clone ở dưới).
Các engine README liệt kê gồm: 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 và 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 cô lập không có ở mọi engine.
Về tiền: bản tự host miễn phí, nhưng bạn trả tiền cho nhà cung cấp mô hình nếu engine của bạn tính phí. README không nói rõ về yêu cầu phần cứng như GPU, nên mình không khẳng định gì ở điểm này.
Suparagent gửi cho engine bạn chọn câu lệnh của bạn và ngữ cảnh cần cho lượt đó, gồm cả 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, dữ liệu đó thuộc điều khoản của nhà cung cấp. Đừng đặt tài liệu nhạy cảm vào thư mục làm việc của agent nếu bạn chưa yên tâm về engine.
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
- Tải mã nguồnDùng git clone để lấy repo về máy
- Vào thư mục desktopMở terminal tại thư mục suparagent/desktop
- Chạy ứng dụngGõ lệnh chạy bản desktop
- Thiết lập lần đầuChọn engine, thư mục làm việc và chế độ duyệt
A.Chuẩn bị công cụ
Trước hết hãy 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 nhất: mở ứng dụng khi chưa có engine nào sẵn sàng thì sẽ không có gì để chat.
Bạn kiểm tra nhanh hai công cụ đầu tiên bằng các lệnh phổ thông sau (chỉ để xem phiên bản):
node --version
uv --versionLệnh node --version phải hiện số 22 trở lên. README không nêu cách cài từng công cụ ngoài việc dẫn tới trang của uv, nên bạn tự cài theo trang chủ của Node.js và uv.
B.Tải mã nguồn và chạy ứng dụng
Mở terminal (PowerShell hoặc Command Prompt trên Windows, Terminal trên macOS hoặc Linux) ở thư mục bạn muốn đặt dự án, rồi chạy đúng ba lệnh trong README:
git clone https://github.com/Anil-matcha/suparagent.git
cd suparagent/desktop
npm run appLệnh thứ nhất tải mã nguồn về. Lệnh thứ hai đi vào thư mục desktop, và bạn phải đứng đúng thư mục này thì lệnh thứ ba mới chạy. Lệnh thứ ba mở ứng dụng. README không ghi bước cài thêm gói nào (như npm install) trước npm run app. Nếu lệnh báo thiếu gói, hãy xem hướng dẫn desktop setup trong thư mục docs/ của repo thay vì đoán lệnh.
Ngoài ra repo có sẵn Dockerfile, compose.yaml và file run-desktop.bat, nhưng README phần Quick start không hướng dẫn dùng chúng. Nếu muốn chạy trên server, README chỉ tới Self-hosting guide; hãy đọc nó trong docs/ thay vì tự ghép lệnh.
C.Thiết lập lần đầu
Khi mở lần đầu, ứng dụng yêu cầu bạn chọn engine, thư mục làm việc và chế độ duyệt. Sau đó README gợi ý bốn việc:
- Vào Settings → Engines và xác nhận có một engine đã sẵn sàng.
- Tạo một agent với tên, công việc rõ ràng và một thư mục làm việc.
- Bắt đầu chat. Chọn Ask first để agent dừng lại hỏi bạn trước các hành động cần duyệt.
- Thêm đồng đội hoặc tạo routine khi bạn muốn chia việc hay lặp lại việc.
Nếu bạn chỉ muốn dùng bản có sẵn, README nói có trình cài đặt desktop ở trang Releases. Nhưng chúng còn thử nghiệm và chưa được ký, và Windows hoặc macOS có thể cảnh báo khi mở.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một dòng kết quả cụ thể trong terminal để đối chiếu. Cách kiểm tra thực tế là theo các bước thiết lập:
- Ứng dụng mở ra và cho bạn chọn engine, thư mục làm việc, chế độ duyệt.
- Trong Settings → Engines, engine của bạn hiện ở trạng thái sẵn sàng.
- Bạn tạo được một agent và nhận được câu trả lời khi chat. Hãy thử một việc nhỏ, ví dụ yêu cầu agent liệt kê tên các tệp trong thư mục làm việc.
- Với chế độ Ask first, khi agent định làm điều gì cần duyệt, ứng dụng hiện yêu cầu và chờ bạn bấm đồng ý hoặc từ chối.
Nếu cả bốn điều trên đều ổn thì bạn đã cài thành công.
V.Dùng vào việc thật
Trước khi vào từng tình huống, bạn nên nhớ một nguyên tắc để dùng cho đỡ lo.
Cho agent làm việc thay bạn, nhưng đừng cho nó quyết định thay bạn.
Ông 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 và mỗi tuần phải gom ghi chú, báo cáo rời rạc thành một bản tóm tắt. Đây cũng chính là ví dụ trong README.
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" và "Biên tập". Cho cả ba cùng một thư mục dự án, và đặt engine của trưởng nhóm là Claude hoặc Codex. Sau đó nhắn cho trưởng nhóm một câu như:
Hãy soạn 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. Chia việc cho Nghiên cứu và Biên tập rồi tổng hợp lại.Kết quả: trưởng nhóm chia nhỏ yêu cầu, giao cho hai agent kia làm 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 khi cài đặt yêu cầu. Khi quy trình đã ổn, bạn biến nó thành routine hằng tuần và xem kết quả mỗi lần chạy.
B.Chủ shop theo dõi việc cần xử lý mỗi sáng
Bối cảnh: bạn bán hàng, thư và lịch hẹn dồn lại, dễ sót việc.
Cách làm: kết nối Gmail và Google Calendar qua khoá Composio của bạn, rồi cấp quyền cho một agent Claude hoặc Codex. Mỗi sáng mở màn hình Today. Nó gom các yêu cầu duyệt, câu hỏi, kết quả routine và việc đến hạn, và có thể hiện thư cùng lịch ở chế độ chỉ đọc.
Kết quả: bạn nhìn một chỗ là biết việc nào cần mình quyết định. Lưu ý README ghi rằng phần ứng dụng kết nối mới được thử với một dịch vụ Composio giả, chưa thử với dịch vụ thật, nên hãy bắt đầu với việc ít rủi ro.
C.Dev chia việc cho nhiều agent
Bối cảnh: bạn là lập trình viên và muốn một agent đọc mã, một agent viết ghi chú thay đổi.
Cách làm: tạo hai agent cùng thư mục dự án, đặt chế độ Plan only hoặc Ask first để chúng chỉ lập kế hoạch hay hỏi trước khi sửa. Dùng bảng công việc để giao từng việc và xem lại các lần thử.
Kết quả: mỗi agent có hội thoại riêng, bạn xem lại được toàn bộ hoạt động công cụ và quyết định duyệt. Nếu cần chạy mã trong môi trường tách biệt, bạn có thể bật máy tính cô lập bằng Docker, nhưng README ghi phần này còn thử nghiệm.
D.Dùng lại hướng dẫn cho việc lặp đi lặp lại
Bối cảnh: bạn hay giao cùng một kiểu việc, ví dụ soạn thư phản hồi khách theo một giọng văn cố định.
Cách làm: lưu hướng dẫn đó thành skill, hoặc tạo agent từ một mẫu có sẵn. Skill là chỉ dẫn bạn chọn áp dụng cho một tin nhắn cụ thể. Khi cần, bạn chọn skill đó thay vì gõ lại cả đoạn dài.
Kết quả: kết quả đồng đều hơn và bạn đỡ phải gõ lại. Muốn biết cách tạo skill và mẫu chi tiết, hãy xem hướng dẫn skills và templates trong thư mục docs/.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh npm hoặc uv báo không tìm thấy
Nguyên nhân thường gặp là chưa cài Node.js hay uv, hoặc cài xong mà chưa mở lại terminal. Hãy đóng terminal, mở cửa sổ mới rồi chạy node --version và uv --version. Nếu vẫn lỗi, cài lại theo trang chủ của từng công cụ.
B.Chạy npm run app mà không có gì xảy ra hoặc báo lỗi
Hãy kiểm tra bạn đang đứng đúng thư mục suparagent/desktop. Kiểm tra tiếp phiên bản Node có từ 22 trở lên không. Nếu lỗi báo thiếu gói, README chưa ghi bước cài gói riêng, nên hãy đọc hướng dẫn desktop setup trong docs/ hoặc hỏi trên Discord và GitHub Issues của dự án.
C.Ứng dụng mở được nhưng engine không sẵn sàng
Với engine CLI, bạn phải cài và đăng nhập engine đó trước khi mở ứng dụng. Với engine API, hãy điền cấu hình trong Settings → Engines. Chỉ dán khoá API vào chỗ ứng dụng cho nhập, không dán vào chat hay tệp công khai. Theo README, khoá lưu qua Suparagent được mã hoá trên máy hoặc server của bạn.
D.Routine không chạy đúng giờ
README nói routine chạy ở backend, nên backend phải luôn chạy. Nếu bạn tắt máy hoặc tắt ứng dụng thì lịch sẽ không chạy. Với việc cần chạy đều, hãy cân nhắc tự host trên một server luôn bật.
E.Windows hoặc macOS cảnh báo khi mở trình cài đặt
README ghi trình cài đặt còn thử nghiệm và chưa được ký. Cảnh báo là điều dễ xảy ra. Hãy chỉ tải từ trang Releases chính thức của repo, và nếu không yên tâm thì dùng cách chạy từ mã nguồn ở trên.
VII.Có nên dùng không
Điểm mạnh. Bạn có cả một "văn phòng AI" trong một ứng dụng: agent có tên, trí nhớ xem và sửa được, routine, bảng việc, lịch và nhiều mức duyệt. Dữ liệu của bản desktop và self-host nằm trên máy hoặc server của bạn. Bạn không bị khoá vào một mô hình, vì engine có thể là Claude, Codex, Gemini, Cursor, OpenRouter hay mô hình chạy cục bộ qua Ollama hoặc LM Studio. Giấy phép Apache-2.0 cho phép dùng và chỉnh sửa khá thoải mái.
Giới hạn. Chính README nhắc dự án còn sớm và thay đổi nhanh. Bản tự host chỉ có một chủ sở hữu, có thể mời đồng đội, và mọi người dùng chung agent, hội thoại và trí nhớ; nó không phải dịch vụ cho nhiều tổ chức. Ngoài ra:
- Giao việc theo nhóm còn mới, và trưởng nhóm cần dùng Claude hoặc Codex.
- App điện thoại mới thử trên Android, chưa có iOS, chưa có thông báo đẩ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à tuỳ chọn thử nghiệm.
- Trình cài đặt desktop chưa được ký.
- 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 được kiểm thử trên dịch vụ thật.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần hỏi đáp nhanh, một ứng dụng chat thông thường sẽ đơn giản hơn nhiều. Nếu bạn cần công cụ ổn định cho công việc quan trọng hoặc cho nhiều tổ chức, hãy cân nhắc kỹ trước khi dựa vào một dự án đang thử nghiệm. README cũng có bản dịch vụ hosted riêng, tính phí theo gói, nhưng đó là sản phẩm tách biệt với bản mã nguồn mở. Nếu bạn muốn thử, hãy bắt đầu từ bản desktop với chế độ Ask first và một thư mục không chứa dữ liệu quan trọng.
Câu hỏi thường gặp
Suparagent có miễn phí không?
Mã nguồn mở theo giấy phép Apache-2.0 và bản desktop hay tự host không thu phí. Tuy vậy repo không kèm mô hình AI, nên nếu engine của bạn tính tiền thì bạn trả cho nhà cung cấp đó. Dịch vụ hosted là sản phẩm riêng với các gói trả phí.
Tôi có cần GPU không?
Tư liệu không nêu yêu cầu GPU. Suparagent dùng engine bạn chọn, và README liệt kê cả engine qua API lẫn mô hình cục bộ qua Ollama hoặc LM Studio. Nếu bạn chạy mô hình cục bộ thì cấu hình máy phụ thuộc vào mô hình đó, tư liệu chưa có thông tin cụ thể.
Có chạy được trên Windows không?
Repo có file run-desktop.bat, và README mô tả bản desktop chạy từ mã nguồn bằng Node.js 22+ và uv. Tuy nhiên README cũng ghi các trình cài đặt desktop còn thử nghiệm, chưa được ký và chưa kiểm chứng nhiều nền tảng. Bạn nên thử trước với việc không quan trọng.
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 ở thư mục dữ liệu hoặc cơ sở dữ liệu của bạn, còn khoá API lưu qua Suparagent được mã hoá. Nhưng engine bạn chọn vẫn nhận câu lệnh và ngữ cảnh của lượt đó, nên dữ liệu đó thuộc điều khoản của nhà cung cấp engine. Bản hosted do Suparagent xử lý theo chính sách riêng.
Agent có tự làm việc mà không hỏi tôi không?
Tuỳ chế độ bạn chọn: Ask first, Accept edits, Approve for me (cho Claude, Codex và Cursor) hoặc Plan only. README nói routine không bao giờ tự phê duyệt một hành động. Với kết nối ứng dụng, các thay đổ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, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent CLI dùng giao thức ACP, OpenRouter và API tương thích OpenAI như Ollama hay LM Studio. Không phải engine nào cũng hỗ trợ mọi tính năng. Riêng trưởng nhóm cần dùng Claude hoặc Codex.
Khác gì so với bản hosted ở suparagent.ai?
Bản hosted là dịch vụ tách biệt do Suparagent vận hành, có gói trả phí và tài khoản riêng. Bản mã nguồn mở là desktop và server tự host, dữ liệu nằm ở máy hoặc server của bạn. Chi tiết giá và chính sách bạn nên xem trên trang chính thức của dịch vụ.


