Ruflo: điều phối nhiều AI agent cho Claude Code và Codex — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về ruvnet/ruflo — 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: ruflo: điều phối nhiều AI agent cho Claude Code và Codex — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Ruflo (trước đây là Claude Flow) là một “agent harness”, tức lớp công cụ bao quanh Claude Code và Codex để thêm agent chuyên biệt, bộ nhớ qua nhiều phiên, hook và MCP server. Bạn dùng nó để Claude Code làm việc theo nhóm agent thay vì một mình. Cài khá đơn giản: cần Node 20 trở lên và chạy một lệnh `npx ruflo@latest init` trong thư mục dự án.
Ruflo là một “agent harness”: lớp công cụ đặt quanh Claude Code và Codex để biến một trợ lý AI đơn lẻ thành một nhóm agent biết phối hợp, nhớ việc cũ và có giới hạn an toàn. Tác giả mô tả ngắn gọn: mô hình AI lo viết, còn harness lo cấp công cụ, bộ nhớ, vòng lặp và các cơ chế kiểm soát để AI làm việc được thật.
Repo này ban đầu có tên Claude Flow, nay đổi tên thành Ruflo. Theo README, nó thêm hơn 100 agent chuyên biệt, các “swarm” (nhóm agent phối hợp), bộ nhớ tự học, liên lạc giữa nhiều máy (federation) và các rào chắn bảo mật. Hiện repo có khoảng 81.582 sao và 9.607 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.
Bạn nên đọc bài này nếu đang dùng Claude Code hoặc Codex và muốn giao những việc lớn hơn, như rà soát cả repo, viết test, ghi nhớ quyết định giữa các buổi làm việc. Điểm đáng giá nhất: README nói bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Sau khi chạy init, bạn cứ dùng Claude Code như bình thường, các hook sẽ tự định tuyến tác vụ ở nền.
ruvnet/ruflo
Ruflo là lớp điều phối bao quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server vào dự án chỉ bằng một lệnh npx.
I.Ruflo làm được gì
Dưới đây là các nhóm tính năng chính, giải thích theo lợi ích thực tế.
A.Nhóm agent làm việc cùng nhau
Thay vì một cuộc trò chuyện dài với một AI, Ruflo cho phép bạn nhờ cả một “swarm”. README ví dụ: yêu cầu swarm rà soát repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Cách này hợp với việc có nhiều bước, mỗi bước cần một vai khác nhau.
B.Bộ nhớ giữa các phiên
Claude Code thường “quên” khi bạn đóng phiên. Ruflo bổ sung bộ nhớ dạng vector để agent nhớ kinh nghiệm cũ và dùng lại khi định tuyến việc mới. README lưu ý đây là mô hình học ở mức khái niệm: phần truy xuất vector cục bộ có thể chạy không cần LLM, nhưng vẫn cần embedding và các module học được cấu hình.
C.Bảng điều khiển ngay cạnh Claude Code
Plugin ruflo-console là một “cockpit”: theo dõi workflow, agent, mô hình, token và chi phí bên cạnh Claude Code. Bạn mở nó bằng lệnh /ruflo. Bạn cũng xem được log và kết quả từng lần chạy, tìm kiếm, lọc lỗi, phát lại và so sánh.
D.Để Claude điều khiển, bạn đặt giới hạn
Trong Settings có mục “Claude control”. Bạn chọn mức quyền read, write, manage hoặc full, và chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask. README nói các hành động liên quan mạng, chi tiêu và phá huỷ vẫn phải xác nhận ngay cả khi để auto. Có nút “Take back control” để dừng ngay.
E.Hệ plugin lớn
Theo README có 48 plugin (cộng thêm 3 plugin bên ngoài), chia nhóm: điều phối, bộ nhớ, học tập, kiểm thử, bảo mật, DevOps. Vài ví dụ: ruflo-swarm (điều phối nhiều agent), ruflo-testgen (tìm test còn thiếu và sinh test), ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí), ruflo-security-audit (quét lỗ hổng), ruflo-aidefence (chặn prompt injection, phát hiện thông tin cá nhân).
F.Dùng với Codex và các client MCP khác
Không chỉ Claude Code. Codex hay bất kỳ client MCP nào cũng trỏ được vào MCP server của Ruflo bằng lệnh npx -y ruflo@latest mcp start. README còn nhắc tới chế độ cho Grok Build qua npx ruflo init --grok.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu một vài yêu cầu rõ ràng:
- Node.js từ 20.0.0 trở lên. Đây là yêu cầu trong
package.json. Bạn cần Node để chạy được lệnhnpx. - Claude Code nếu muốn dùng cách cài qua plugin: cần bản 2.1.287 trở lên. Riêng lệnh cài từ terminal (
claude plugin install ...) cần bản 2.1.292 trở lên. - Một dự án (thư mục) để chạy
init. Lệnh này ghi file vào thư mục dự án.
Về hệ điều hành, phần cứng, tài khoản hay API key, phần README mình có không ghi yêu cầu cụ thể. Nếu bạn dùng Claude Code hay Codex, tài khoản của chúng bạn đã có sẵn. Muốn biết thêm, xem thư mục docs/ và file README.md trong repo.
Các plugin “mods” chạy với quyền tài khoản của bạn và không được cách ly (sandbox). README khuyên bạn đọc mã trước khi cài. Hãy làm theo, nhất là khi dùng máy công việc.
III.Cài đặt từng bước
README đưa ra mấy đường cài. Cách chính, đơn giản nhất là dùng npx ruflo@latest init. Mình tóm tắt trước:
- Mở terminal đúng chỗVào thư mục dự án mà bạn muốn dùng Ruflo
- Chạy initGõ npx ruflo@latest init để thêm agent, hook, bộ nhớ và MCP server
- Mở Claude CodeMở lại Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao việc thửNhờ Claude dùng swarm của Ruflo làm một việc nhỏ
- (Tuỳ chọn) Cài bản pluginDùng /plugin marketplace add nếu không muốn thêm file vào dự án
A.Mở terminal trong thư mục dự án
Đây là chỗ người mới hay vấp. Lệnh init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng thư mục dự án trước khi chạy. Trên Windows bạn có thể mở PowerShell rồi dùng cd vào thư mục của mình. Bạn không cần tải mã nguồn về, vì npx tự lấy gói.
cd duong-dan-toi-du-an-cua-banduong-dan-toi-du-an-cua-ban là chỗ để bạn thay bằng đường dẫn thật.
B.Chạy lệnh init
Lệnh này là cách khởi đầu chính theo README:
npx ruflo@latest initTheo README, init thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Ở bảng so sánh, README nói cách này tạo ra các file như .claude/, .claude-flow/, CLAUDE.md, file helper và settings trong thư mục làm việc. Vì vậy hãy chạy trong dự án có quản lý phiên bản (git) để dễ xem lại những gì đã thay đổi.
Nếu muốn thiết lập tương tác từng câu hỏi, README có thêm lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code và giao việc đầu tiên
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận cấu hình ở lần khởi động kế tiếp. Nếu đang mở sẵn, hãy thoát ra và mở lại. Rồi thử một câu lệnh mẫu từ README:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.Bạn có thể viết bằng tiếng Việt, nhưng câu mẫu gốc là tiếng Anh, nên mình giữ nguyên để chắc chắn.
D.Cách khác: chỉ cài plugin cho Claude Code (không thêm file vào dự án)
Cách này cài công cụ lõi, bảng điều khiển và các mod, “không thêm file nào vào dự án”. Cần Claude Code 2.1.287 trở lên. Bạn gõ các lệnh sau bên trong Claude Code (không phải ở terminal thường):
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/rufloTừng dòng làm gì: dòng đầu thêm “chợ” plugin của Ruflo; ba dòng install cài ba plugin; /reload-plugins nạp lại; /ruflo mở bảng điều khiển. Nếu dùng Claude Code 2.1.292 trở lên, bạn cũng có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloREADME nêu rõ: cách plugin chỉ cho slash command, một vài skill và định nghĩa agent. Nó không cài hook và chỉ đăng ký MCP server nếu bạn cài ruflo-core. Muốn đủ “vòng lặp” đầy đủ (98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon) thì dùng npx ruflo@latest init.
E.Cách khác: Codex hoặc client MCP khác
Không cần thiết lập dự án. Trong phần cấu hình MCP của client, đặt command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Bạn cũng có thể chạy thử trực tiếp:
npx -y ruflo@latest mcp startF.Cách khác: giao diện terminal
Bảng điều khiển còn chạy riêng được, không cần Claude Code:
npx ruflo tuiThêm --plain để in ra một khung duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra theo tư liệu rất đơn giản:
- Sau
npx ruflo@latest init, hãy xem trong thư mục dự án đã có.claude/,.claude-flow/vàCLAUDE.mdchưa. - Mở lại Claude Code trong thư mục đó, gõ
/ruflo. Nếu bảng điều khiển hiện ra, bạn đã cài được phần cockpit. - Với cách plugin, gõ
/plugin, rồi xem tên các plugin đã xuất hiện trong dòng “active mods”. - Với client MCP, kiểm tra client có liệt kê được các công cụ của server
ruflokhông. README chưa nêu màn hình mẫu cụ thể cho từng client, nên bạn xem tài liệu của client đó.
Nếu cần thử nhanh nhất, hãy giao câu lệnh mẫu ở trên và xem Claude Code có bắt đầu chia việc cho nhiều agent không.
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ả. Kết quả thực tế còn phụ thuộc dự án và mô hình bạn đang dùng.
A.Lập trình viên mới nhận một repo lạ
Bạn vừa vào công ty, được giao một repo lớn mà chưa ai giải thích. Sau khi chạy init và mở lại Claude Code, bạn nhờ:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.Kết quả mong đợi theo README: Claude chia việc cho các agent, chỉ ra module rủi ro nhất, viết test và tóm tắt thay đổi. Bạn nên đọc lại phần test trước khi chạy hoặc commit, đừng tin mù quáng.
Agent = Model + Harness. Model viết, còn harness lo công cụ, bộ nhớ và giới hạn để nó làm việc được thật.
Ông T
B.Người làm sản phẩm muốn theo dõi chi phí AI
Bạn là người phụ trách một dự án nhỏ và lo hoá đơn token. Cài ruflo-console rồi gõ /ruflo để xem workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Muốn có cảnh báo, README liệt kê plugin ruflo-cost-tracker với chức năng theo dõi token, đặt ngân sách và cảnh báo chi phí:
/plugin install ruflo-cost-tracker@rufloTên plugin này nằm trong danh sách README, nhưng mình không có tư liệu chi tiết về cách cấu hình ngân sách của nó. Bạn xem thư mục plugins/ trong repo.
C.Giao Claude tạo một “mission” có kiểm soát
Đây là bài thử an toàn mà README mô tả từng bước. Bạn đặt ranh giới trước, rồi mới giao việc:
- Cài console như ở phần trên, mở
/ruflo, chọn Settings → Claude control → write + ask. - Gõ yêu cầu mẫu: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
- Claude mở mục Missions và đặt mục tiêu. Bạn xác nhận hành động tạo đang chờ duyệt.
- Kiểm tra: mục Missions có mục tiêu mới, mục Overview có ghi lại hành động.
README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Nếu muốn dừng, bấm “Take back control”.
D.Nhóm nhỏ muốn kiểm thử và rà bảo mật
Bạn là dev trong nhóm nhỏ, không có người chuyên test hay bảo mật. Trong danh sách plugin của README có ruflo-testgen (tìm test còn thiếu và sinh test), ruflo-security-audit (quét lỗ hổng và CVE) và ruflo-aidefence (chặn prompt injection, phát hiện PII). Bạn cài thử từng plugin theo cùng cú pháp:
/plugin install ruflo-testgen@ruflo
/plugin install ruflo-security-audit@rufloSau đó nhờ Claude Code gọi các lệnh slash hoặc agent mà plugin cung cấp. Danh sách lệnh cụ thể của từng plugin README chưa nêu, bạn sẽ thấy khi gõ / trong Claude Code sau khi cài.
VI.Lỗi hay gặp và cách xử lý
Phần này mình tổng hợp từ cách công cụ hoạt động. Một số lỗi là suy ra từ yêu cầu trong README chứ không phải log lỗi chính thức.
A.Gõ lệnh npx mà báo không tìm thấy lệnh
Thường do chưa cài Node.js, hoặc terminal mở trước khi cài nên chưa nhận. Hãy cài Node bản 20 trở lên (đây là yêu cầu trong package.json), đóng terminal rồi mở lại. Kiểm tra bằng lệnh node --version.
B.Lệnh /plugin install báo không nhận
Có thể Claude Code của bạn quá cũ. Cách plugin cần bản 2.1.287 trở lên, lệnh từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi thử lại. Nhớ gõ các lệnh /plugin ... bên trong Claude Code chứ không gõ vào terminal thường.
C.Chạy init xong mà Claude Code chưa thấy gì
README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn Claude Code và mở lại trong đúng thư mục bạn đã chạy init. Nếu mở ở thư mục khác, nó sẽ không thấy .claude/ của dự án.
D.Dự án bỗng có nhiều file lạ
Đó là chuyện bình thường: init thêm .claude/, .claude-flow/, CLAUDE.md và các file helper. Nếu bạn không muốn thêm file, hãy dùng cách plugin (không thêm file nào). Với Grok, README có cờ --dry-run để xem trước, nhưng mình chỉ có tư liệu về cờ này đi kèm --grok, nên đừng tự thêm vào lệnh khác khi chưa kiểm tra.
E.Cài một plugin từ hai nơi thì lệnh bị nhân đôi
README cảnh báo với các plugin bên ngoài như agentic-qe-fleet, agentdb, agentic-flow: chỉ nên cài từ một marketplace. Nếu bật từ cả hai, mod và lệnh sẽ nạp hai lần. Hãy gỡ bản thừa rồi chạy /reload-plugins.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh (một lệnh), có nhiều đường cài cho nhiều kiểu người dùng, giấy phép MIT, hỗ trợ cả Claude Code lẫn Codex. Có sẵn bảng điều khiển để nhìn thấy agent đang làm gì, và có cơ chế phân quyền cho cả phần Claude tự điều khiển. Dự án cũng vẫn được cập nhật đều.
Giới hạn. Hệ thống rất lớn: hàng chục plugin, hàng trăm công cụ MCP. Người mới dễ choáng, nên bắt đầu với init và một việc nhỏ. README còn tự nói rõ một số demo dùng dữ liệu mẫu hoặc chỉ phát lại khung hình, và không chứng minh được việc swarm hoàn thành công việc thật hay bộ nhớ gọi lại đúng. Hãy tự thử trên dự án của bạn. Ngoài ra init ghi file vào dự án, và các mod không được sandbox.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần Claude Code làm việc nhỏ, đơn lẻ, thì dùng Claude Code thuần là đủ, không cần thêm một lớp điều phối. Nếu bạn không muốn thêm file vào dự án, hãy dùng cách plugin hoặc cấu hình MCP. Nếu bạn cần cam kết về bảo mật dữ liệu ở mức tổ chức, hãy đọc SECURITY.md trong repo trước khi triển khai, vì mình chưa có thông tin chi tiết hơn.
Tóm lại, Ruflo hợp với người đã quen Claude Code và muốn nâng lên làm việc theo nhóm agent có trí nhớ. Hãy bắt đầu nhỏ: chạy init trong một dự án thử, giao đúng một việc, rồi xem kết quả.
Câu hỏi thường gặp
Ruflo có miễn phí không?
Repo dùng giấy phép MIT nên mã nguồn dùng tự do. Tuy nhiên bạn vẫn trả chi phí cho dịch vụ AI bạn kết nối (như Claude Code hay Codex) theo gói của chúng. README có plugin theo dõi token và chi phí, nhưng chưa nói gì về một bảng giá riêng của Ruflo.
Ruflo khác gì Claude Code?
Claude Code là công cụ lập trình AI. Ruflo là lớp bao quanh nó, thêm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook và MCP server. README gọi Ruflo là “agent harness” và nói bạn vẫn dùng Claude Code như bình thường sau khi cài.
Cần cài gì trước khi dùng?
Theo package.json, bạn cần Node.js từ 20.0.0 trở lên để chạy npx. Với cách cài qua plugin, cần Claude Code bản 2.1.287 trở lên (2.1.292 nếu cài bằng lệnh từ terminal).
Có dùng được với Codex hoặc công cụ khác ngoài Claude Code không?
Có. README nói Codex và các client MCP khác trỏ tới lệnh npx với đối số -y, ruflo@latest, mcp, start. README cũng có một lệnh riêng để thiết lập cho Grok Build.
Cài Ruflo có thêm file vào dự án của tôi không?
Tuỳ cách cài. Lệnh npx ruflo@latest init thêm các file như .claude/, .claude-flow/ và CLAUDE.md vào dự án. Cách cài plugin cho Claude Code thì README nói không thêm file nào vào dự án.
Dữ liệu của tôi có an toàn không?
README có nhắc rào chắn bảo mật, và phần Claude điều khiển bảng điều khiển có phân quyền, mặc định là read + ask. Các mod chạy bằng quyền tài khoản của bạn và không được sandbox, nên cần đọc mã trước khi cài. Về cam kết bảo mật chi tiết, tư liệu mình có chưa nêu; hãy xem SECURITY.md trong repo.
Có cần GPU hoặc máy mạnh không?
Tư liệu mình có chưa nêu yêu cầu về GPU hay phần cứng. Một plugin trong danh sách có nhắc tìm kiếm tăng tốc GPU, nhưng không có thông tin đó là bắt buộc. Bạn nên xem tài liệu trong thư mục docs/ của repo.


