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

Suparagent: đồng nghiệp AI có tên, bộ nhớ, lịch chạy, cần bạn duyệt — cài đặt và dùng

11 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: đồng nghiệp AI có tên, bộ nhớ, lịch chạy, cần bạn duyệt — 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 'đồng nghiệp AI' có tên, vai trò, bộ nhớ và lịch chạy, chạy trên máy bạn hoặc server của bạn. Bạn tự mang engine (Claude Code, Codex, Gemini, Ollama…) vì repo không kèm mô hình. Cài bản desktop từ mã nguồn cần Node.js 22+, uv và một engine; tác giả cho biết dự án còn ở giai đoạn thử nghiệm.

Suparagent là một không gian làm việc mã nguồn mở 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. Cuộc trò chuyện, trí nhớ, lịch chạy và các yêu cầu phê duyệt đều nằm chung một chỗ. Repo viết bằng Python, giấy phép Apache-2.0, hiện có khoảng 7.041 sao và 913 fork.

Vấn đề nó giải quyết khá quen thuộc. Chat với AI thì mỗi lần lại giải thích từ đầu, AI không nhớ việc tuần trước, và bạn cũng ngại để nó tự làm gì đó trên máy mình. Suparagent cho agent một vai trò cố định, một bộ nhớ bạn đọc và sửa được, một lịch chạy lặp lại, và một nguyên tắc: việc cần duyệt thì dừng lại hỏi bạn. Người hợp nhất là người làm văn phòng hoặc kinh doanh muốn có trợ lý lặp lại việc hằng tuần, và lập trình viên muốn tự chủ hệ thống thay vì phụ thuộc dịch vụ đóng.

Điểm đáng giá nhất là bạn tự mang engine. Repo không kèm mô hình hay gói thuê bao nào. Bạn dùng Claude Code, Codex, Gemini, hoặc cả mô hình chạy cục bộ qua Ollama, tuỳ tài khoản bạn đã có. Xem video ngắn bên dưới để thấy giao diện trước khi cài.

Ứng dụng

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, trí nhớ, lịch chạy riêng và chỉ hành động khi bạn đồng ý.

★ 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, kèm 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, bộ nhớ và mức phê duyệt riêng. Một agent trưởng nhóm có thể chia việc cho các agent chuyên môn, hoặc phối hợp trong phòng chung. Lưu ý: trưởng nhóm cần dùng Claude hoặc Codex.
  • Giữ ngữ cảnh. Agent ghi chú, nhớ lại ghi chú và hội thoại 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ợ 'nhớ sai mà không biết'.
  • Chạy việc theo lịch (routine). Một routine chạy theo lịch, qua webhook hoặc bấm tay. Mỗi kết quả bạn xem lại được; routine không bao giờ tự phê 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, Approve for me (cho Claude, Codex và Cursor) và Plan only. Mọi hoạt động công cụ và quyết định duyệt đều xem được trong app.
  • Nối vớ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 và cấp quyền cho agent Claude hoặc Codex được chọn. Thay đổi vẫn chờ bạn duyệt. Ngoài ra có MCP Marketplace để thêm từng công cụ.
  • 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 nơi; có thể hiển thị 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ử.
  • Skill và mẫu. Lưu hướng dẫn dùng lại, tạo agent từ mẫu có sẵn.
  • Ứng dụng đ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 một lệnh gọi công cụ.
  • 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, duyệt hoặc tải tệp trong workspace, 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), cài theo hướng dẫn trên trang của uv.
  • Ít nhất một engine có sẵn trên cùng máy. Nếu là engine dòng lệnh (CLI), bạn phải cài và đăng nhập nó trước khi mở app. Nếu là engine dùng API, bạn cấu hình trong Settings → Engines.
  • Docker chỉ cần nếu bạn muốn dùng các 'máy tính cô lập' tuỳ chọn cho agent.

Các engine README liệt kê: Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent 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. Không phải engine nào cũng hỗ trợ ảnh đầu vào hay máy tính cô lập.

README không nêu yêu cầu phần cứng như GPU hay dung lượng RAM. Nếu bạn dùng mô hình chạy cục bộ, yêu cầu máy sẽ phụ thuộc vào mô hình đó chứ không phải Suparagent.

Suparagent không kèm mô hình hay thuê bao nào. Dùng engine của nhà cung cấp bên ngoài thì có thể tốn tiền theo tài khoản hoặc API key của bạn. Prompt và nội dung tệp agent đọc sẽ được gửi tới engine đó, nên đừng để agent đọc dữ liệu nhạy cảm nếu bạn chưa yên tâm về điều khoản của nhà cung cấp.

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

Dưới đây là cách chạy bản desktop theo Quick start của README.

  1. Chuẩn bị công cụCài Node.js 22+ và uv
  2. Chuẩn bị engineCài và đăng nhập một engine CLI, hoặc chuẩn bị API key
  3. Tải mã nguồnDùng git clone rồi vào thư mục desktop
  4. Mở appChạy lệnh npm run app
  5. Thiết lập lần đầuChọn engine, workspace, chế độ phê duyệt

A.Cài Node.js, uv và một engine

Kiểm tra phiên bản Node.js của bạn bằng lệnh sau. Kết quả phải từ 22 trở lên.

Terminal
node --version

Với uv, bạn cài theo hướng dẫn trên trang chính thức của uv (README chỉ dẫn tới đó, không ghi lệnh cụ thể). Với engine, ví dụ bạn dùng Claude Code hoặc Codex, hãy cài và đăng nhập nó trong terminal trước khi mở Suparagent. Đây là chỗ người mới hay quên: nếu chưa đăng nhập engine, app sẽ không có gì để chạy.

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

Mở terminal (Windows: PowerShell hoặc Git Bash; macOS/Linux: Terminal) ở thư mục bạn muốn đặt dự án, rồi chạy:

Terminal
git clone https://github.com/Anil-matcha/suparagent.git
cd suparagent/desktop

Lệnh đầu tải mã nguồn về thư mục suparagent. Lệnh thứ hai đi vào thư mục con desktop. Bạn cần máy đã cài Git.

C.Mở ứng dụng

Trong thư mục desktop, chạy:

Terminal
npm run app

README chỉ ghi đúng một lệnh này cho Quick start và không nói thêm bước cài phụ thuộc nào khác. Nếu lệnh báo lỗi thiếu gói, hãy xem hướng dẫn thiết lập desktop trong thư mục docs/ của repo thay vì tự đoán. Repo cũng có file run-desktop.bat ở thư mục gốc, nhưng README không giải thích cách dùng nó, nên mình không khẳng định gì thêm.

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

Lần mở đầu tiên, app hỏi bạn chọn engine, workspace và chế độ phê duyệt. Sau đó làm theo thứ tự README:

  1. Vào Settings → Engines và xác nhận có một engine ở trạng thái sẵn sàng.
  2. Tạo một agent với tên, một 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 những hành động cần duyệt.
  4. Khi cần chia việc hoặc lặp việc, thêm đồng đội hoặc tạo routine.

E.Các cách chạy khác

README còn nhắc bản server tự host (cần máy chủ Linux, HTTPS, Docker hoặc Node.js và uv, cùng một engine) và bản cài đặt sẵn trên trang Releases. README chưa ghi lệnh cài cho server ngay trong phần chính; hãy xem hướng dẫn self-hosting trong thư mục docs/. Repo có sẵn Dockerfile và compose.yaml. Bản installer thì README cho biết còn thử nghiệm và chưa được ký số, nên Windows hoặc macOS có thể hiện cảnh báo.

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

README không đưa ra một lệnh kiểm tra riêng. Dấu hiệu thành công theo tư liệu là:

  • Sau npm run app, cửa sổ ứng dụng mở ra và hỏi chọn engine, workspace, chế độ phê duyệt.
  • Trong Settings → Engines, engine của bạn hiện là sẵn sàng.
  • Bạn tạo được một agent và gửi một tin nhắn, agent trả lời. Với chế độ Ask first, khi agent định làm việc cần duyệt, app sẽ dừng và hỏi bạn.

Thử nhanh: tạo agent tên 'Trợ lý thử', giao việc 'tóm tắt các file văn bản trong thư mục này', trỏ workspace vào một thư mục chứa vài ghi chú, rồi hỏi 'có những gì trong thư mục?'. Nếu agent trả lời dựa trên nội dung thư mục thì mọi thứ đã nối đúng.

V.Dùng vào việc thật

Các tình huống dưới đây bám đúng khả năng README mô tả.

A.Chủ shop: bản tóm tắt tuần từ ghi chú bán hàng

Bạn có một thư mục chứa ghi chú và báo cáo bán hàng mỗi tuần. Tạo agent trưởng nhóm (dùng Claude hoặc Codex) cùng hai agent chuyên môn: một người nghiên cứu, một người biên tập, cho cả ba dùng chung thư mục đó. Ra lệnh cho trưởng nhóm:

text
Đọc các ghi chú và báo cáo trong thư mục này, chuẩn bị bản tóm tắt tuần: doanh thu nổi bật, việc tồn đọng, đề xuất tuần tới.

Trưởng nhóm chia việc cho hai agent kia, mỗi người làm trong cuộc trò chuyện riêng rồi trả về để trưởng nhóm tổng hợp. Bạn theo dõi trong chat và duyệt khi cài đặt yêu cầu. Khi quy trình ổn, đặt nó thành routine hằng tuần.

Việc nào lặp lại mỗi tuần thì giao cho một agent có tên, có bộ nhớ, và vẫn phải xin phép bạn.

Ông T

B.Nhân viên văn phòng: gom việc cần chú ý mỗi sáng

Bạn nối Gmail và Google Calendar qua khoá Composio của mình, chỉ cấp cho một agent Claude hoặc Codex cụ thể. Mỗi sáng mở màn hình Today để thấy phê duyệt đang chờ, câu hỏi từ agent, kết quả routine, việc đến hạn, cùng thư và lịch ở chế độ chỉ đọc. Bạn không cần lục từng cuộc trò chuyện. Lưu ý README cho biết phần ứng dụng kết nối mới được thử với dịch vụ Composio giả lập, chưa thử với dịch vụ thật, nên hãy dùng thận trọng.

C.Người làm nội dung: một agent có trí nhớ về giọng văn

Tạo agent 'Biên tập' với công việc ghi rõ giọng văn bạn muốn. Cho nó ghi chú lại các quy tắc bạn hay sửa. Lần sau agent nhớ lại ghi chú liên quan khi trả lời, và bạn mở phần bộ nhớ để xem, sửa hoặc xoá những gì nó đã lưu. Cách này giúp bạn khỏi dán lại cùng một đoạn hướng dẫn mỗi lần.

D.Lập trình viên: chạy việc định kỳ trên server của mình

Bạn dựng server tự host để agent và routine chạy liên tục. Routine chạy ở backend, nên backend phải luôn bật. Bạn có thể kích hoạt routine bằng webhook từ hệ thống khác, và duyệt hành động từ điện thoại sau khi ghép app điện thoại với server. README nói bản server còn thử nghiệm, 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ớ.

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

A.Settings → Engines không báo engine sẵn sàng

Thường do engine CLI chưa cài hoặc chưa đăng nhập. README nói đăng nhập CLI phải làm trước khi mở app. Hãy thoát app, mở terminal, kiểm tra engine chạy được độc lập, đăng nhập lại nếu cần rồi chạy lại npm run app. Nếu dùng engine API, kiểm tra lại cấu hình trong Settings → Engines.

B.npm run app báo lỗi không tìm thấy lệnh hoặc thiếu gói

Kiểm tra bạn đang đứng đúng thư mục suparagent/desktop và Node.js từ phiên bản 22 trở lên. Kiểm tra uv đã cài. Nếu vẫn lỗi, xem hướng dẫn thiết lập desktop trong docs/ hoặc hỏi trên Issues của repo; đừng tự chạy các lệnh lạ tìm được ngẫu nhiên trên mạng.

C.Máy cảnh báo khi mở bản installer

README nói installer còn thử nghiệm và chưa được ký số, nên hệ điều hành có thể cảnh báo. Chỉ tải từ trang Releases chính thức của repo. Nếu ngại, chạy từ mã nguồn như hướng dẫn ở trên.

D.Agent trưởng nhóm không chia việc được

Tính năng giao việc theo nhóm còn mới, và README yêu cầu agent trưởng nhóm dùng Claude hoặc Codex. Nếu bạn đặt engine khác cho trưởng nhóm, hãy đổi lại.

E.Routine không chạy đúng giờ

Routine chạy ở backend, nên backend phải luôn chạy. Tắt app hoặc máy ngủ thì lịch sẽ không chạy. Với việc cần chạy đều, README gợi ý dựng server tự host thay vì máy cá nhân.

F.Agent cứ dừng chờ duyệt

Đây là hành vi đúng của chế độ Ask first. Bạn mở yêu cầu và chọn cho phép hoặc từ chối. Chỉ khi đã tin một agent mới cân nhắc nới sang chế độ khác, và đừng nới cho agent đang đọc dữ liệu nhạy cảm.

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

Điểm mạnh. Bạn kiểm soát dữ liệu: với bản desktop và tự host, hội thoại, ghi chú, routine và cài đặt nằm trên máy hoặc server của bạn; khoá API lưu qua Suparagent được mã hoá. Bạn chọn engine tuỳ ý, kể cả mô hình cục bộ. Mô hình phê duyệt rõ ràng, và routine không tự duyệt thay bạn. Giấy phép Apache-2.0 cho phép bạn xem và sửa mã.

Giới hạn. Chính README ghi dự án đang phát triển và nhiều phần còn thử nghiệm: bản desktop, server tự host, máy tính cô lập bằng Docker, công cụ trình duyệt. Installer chưa ký số. Ứng dụng điện thoại mới thử trên Android, chưa thử trên iOS, chưa có thông báo đẩy. Phần ứng dụng kết nối qua Composio, MCP Marketplace và chuyển giọng nói thành văn bản chưa được kiểm chứng đầy đủ với dịch vụ thật. Server tự host không phải dịch vụ nhiều tổ chức. Cài đặt cũng đòi hỏi bạn quen dùng terminal.

Chi phí. Bản mã nguồn mở không tính phí, nhưng dùng engine của nhà cung cấp bên ngoài thì có thể phát sinh chi phí. Ngoài ra có dịch vụ hosted riêng, tính phí theo gói, do chính Suparagent vận hành và tách biệt với bản mã nguồn mở.

Khi nào chọn cách khác. Nếu bạn chỉ cần một khung chat AI đơn giản và không muốn đụng terminal, một ứng dụng chat có sẵn sẽ dễ hơn. Nếu việc của bạn quan trọng và không chấp nhận lỗi, đừng dựa hoàn toàn vào bản thử nghiệm này. Hãy bắt đầu với một agent, một thư mục thử và chế độ Ask first, rồi mở rộng dần khi đã quen.

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

Phần mã nguồn mở (bản desktop và tự host) dùng giấy phép Apache-2.0. Tuy nhiên repo không kèm mô hình nào, bạn phải dùng tài khoản, đăng nhập CLI hoặc API key của riêng mình, và việc dùng mô hình có thể tốn tiền. Dịch vụ hosted là sản phẩm riêng, có gói trả phí.

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

Theo README, bạn cần Node.js 22 trở lên, uv và ít nhất một engine trên cùng máy. Docker chỉ cần nếu muốn dùng các máy tính cô lập tuỳ chọn cho agent. README không nêu yêu cầu phần cứng riêng.

Dùng được với những mô hình nào?

README liệt kê Claude Code, 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 hoặc LM Studio. Tính năng khả dụng khác nhau tuỳ engine.

Có chạy được trên Windows không?

README không nêu rõ danh sách hệ điều hành cho bản desktop. Repo có file run-desktop.bat, nhưng README không giải thích nó. README nói installer chưa ký số và mới được kiểm chứng nền tảng ở mức hạn chế, nên hãy xem trang Releases và tài liệu thiết lập desktop trong 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 nằm trong thư mục dữ liệu hoặc cơ sở dữ liệu server của 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 prompt và ngữ cảnh cần thiết, nên nếu dùng dịch vụ đám mây thì dữ liệu đó thuộc đ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?

Tuỳ chế độ bạn chọn: Ask first, Accept edits, Approve for me (cho Claude, Codex, Cursor) hoặc Plan only. Riêng routine thì README khẳng định nó không bao giờ tự phê duyệt một hành động.

Dự án đã ổn định để dùng cho việc quan trọng chưa?

README ghi rõ dự án đang phát triển tích cực và nhiều phần còn thử nghiệm, như bản server, máy tính Docker, ứng dụng điện thoại. Tác giả khuyên xem phần Known limitations trước khi dựa vào nó cho việc quan trọ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 Node.js, uv và một engine
    2. B.Tải mã nguồn về máy
    3. C.Mở ứng dụng
    4. D.Thiết lập lần đầu
    5. E.Các cách chạy khác
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop: bản tóm tắt tuần từ ghi chú bán hàng
    2. B.Nhân viên văn phòng: gom việc cần chú ý mỗi sáng
    3. C.Người làm nội dung: một agent có trí nhớ về giọng văn
    4. D.Lập trình viên: chạy việc định kỳ trên server của mình
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Settings → Engines không báo engine sẵn sàng
    2. B.npm run app báo lỗi không tìm thấy lệnh hoặc thiếu gói
    3. C.Máy cảnh báo khi mở bản installer
    4. D.Agent trưởng nhóm không chia việc được
    5. E.Routine không chạy đúng giờ
    6. F.Agent cứ dừng chờ duyệt
  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ỏ.