Ruflo: điều phối nhóm agent AI 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: lớp công cụ bọc quanh Claude Code và Codex để thêm agent chuyên biệt, bộ nhớ qua các phiên, hook tự động và MCP server. Bạn chỉ cần chạy 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ộng nên nên bắt đầu từ việc đơn giản.
Ruflo là một "agent harness" mã nguồn mở: một lớp công cụ đặt quanh Claude Code và Codex, giúp các trợ lý AI này làm việc có tổ chức hơn. Theo README, mô hình AI chỉ lo phần viết, còn harness lo phần còn lại: công cụ, bộ nhớ, vòng lặp kiểm tra và các giới hạn an toàn. Repo này tự gọi mình là phần harness đó.
Nếu bạn đã dùng Claude Code và thấy mỗi phiên làm việc lại bắt đầu từ đầu, hoặc muốn giao một việc lớn cho nhiều agent cùng làm, Ruflo nhắm đúng vào chỗ đó. Người dùng phù hợp là lập trình viên mới đến trung bình, người làm sản phẩm, và dân văn phòng đã quen Claude Code. Bạn không cần học hết các công cụ bên trong. README nói rõ: sau khi chạy init, cứ dùng Claude Code như bình thường, hệ thống hook sẽ tự điều phối việc ở phía sau.
Điểm đáng giá nhất là cách cài rất ngắn: một lệnh npx trong thư mục dự án. Repo hiện có khoảng 81.588 sao và 9.608 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.
ruvnet/ruflo
Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm nhiều agent chuyên biệt, bộ nhớ, hook và MCP server, cài bằng một lệnh npx.
I.Ruflo làm được gì
Dưới đây là những tính năng chính theo README, kèm lợi ích thực tế.
A.Thêm agent và nhóm agent (swarm)
Sau khi cài, Claude Code có thêm nhiều agent chuyên biệt. README ghi con số 100+ agent ở phần giới thiệu và 98 agent ở bảng so sánh cách cài. Các agent có thể tự chia nhóm để làm chung một việc. Lợi ích: bạn giao một việc lớn như "review cả repo" thay vì chia nhỏ từng bước bằng tay.
B.Bộ nhớ qua các phiên
Ruflo có bộ nhớ để agent nhớ lại kinh nghiệm giữa các phiên làm việc, kèm tìm kiếm vector. README lưu ý phần "tự học" là mô hình khái niệm. Việc 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ấu hình. Lợi ích: bớt phải giải thích lại bối cảnh dự án.
C.Hook tự động định tuyến việc
Hook là các đoạn chạy tự động khi Claude Code làm việc. Theo README, hook tự chuyển việc cho agent phù hợp và học từ các mẫu thành công. Bạn không cần nhớ lệnh nào.
D.MCP server
Ruflo đi kèm một MCP server, nên Codex và các ứng dụng hỗ trợ MCP khác cũng dùng được. README nêu có 406 công cụ MCP và 61 lệnh CLI, nhưng nhấn mạnh là bạn không cần học hết.
E.Bảng điều khiển (console)
Plugin ruflo-console là một "buồng lái" cạnh Claude Code: xem workflow, agent, mô hình, token và chi phí. Bạn mở nó bằng lệnh /ruflo trong Claude Code, hoặc chạy riêng ở terminal.
F.Kho plugin
README liệt kê 48 plugin, chia theo nhóm: điều phối, bộ nhớ, học và trí tuệ, kiểm thử chất lượng, bảo mật, kiến trúc, DevOps, mở rộng. Ví dụ ruflo-testgen tìm test còn thiếu và tạo test, ruflo-cost-tracker theo dõi token và đặt ngân sách, ruflo-security-audit quét lỗ hổng.
G.Liên kết nhiều máy (federation)
Theo README, agent trên các máy khác nhau có thể trao đổi an toàn. Đây là tính năng nâng cao, người mới chưa cần.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu những điều sau:
- Node.js từ phiên bản 20.0.0 trở lên. Đây là yêu cầu trong
package.json. Lệnhnpxđi kèm Node. - Claude Code nếu bạn muốn dùng đường cài đầy đủ. Muốn cài bằng plugin thì cần Claude Code 2.1.287 trở lên. Lệnh
claude plugin installở terminal cần 2.1.292 trở lên. - Một dự án (thư mục) để cài vào. Lệnh
initghi file vào thư mục bạn đang đứng. - Hoặc Codex / ứng dụng MCP khác nếu bạn không dùng Claude Code.
Tư liệu chưa nói rõ về hệ điều hành hỗ trợ, yêu cầu phần cứng hay API key bắt buộc. Phần Claude Code và Codex vẫn cần tài khoản riêng của chúng, nên bạn nhớ đăng nhập sẵn. Nếu cần chi tiết hơn, xem README và thư mục docs/ trong repo.
Tên gói npm trong tư liệu là claude-flow (tên cũ), còn README dùng lệnh ruflo. Bạn cứ gõ lệnh đúng như hướng dẫn dưới đây. Plugin chạy bằng quyền tài khoản của bạn và không bị cô lập, nên hãy đọc mã nguồn trước khi cài.
III.Cài đặt từng bước
- Kiểm tra NodeĐảm bảo máy có Node 20 trở lên
- Mở terminal trong dự ánĐứng đúng thư mục bạn muốn dùng Ruflo
- Chạy initMột lệnh npx để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude CodeClaude Code nạp cấu hình mới khi khởi động
- Giao thử một việc thậtDán một câu lệnh mẫu để xem swarm làm việc
A.Kiểm tra Node
Trước hết xác nhận máy có Node 20 trở lên. Lệnh node --version là lệnh phổ thông của Node, README không ghi riêng lệnh này.
node --versionNếu số đầu nhỏ hơn 20, hãy nâng cấp Node trước khi làm tiếp.
B.Mở terminal trong thư mục dự án
Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. README dặn chạy "trong thư mục dự án", vì init ghi file vào đúng nơi bạn đứng. Nếu chưa có dự án, bạn có thể tạo một thư mục thử rồi cd vào đó.
cd duong-dan-toi-du-an-cua-banC.Chạy lệnh init
Đây là lệnh chính theo README:
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh trong README, nó tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings. Nếu dự án của bạn đã có CLAUDE.md, hãy sao lưu trước. README không nói rõ trường hợp file đã tồn tại sẽ xử lý ra sao.
Muốn cài có hướng dẫn từng câu hỏi, README có chế độ wizard:
npx ruflo@latest init wizardD.Mở lại Claude Code
Mở Claude Code trong cùng thư mục. README nói Claude Code nạp cấu hình mới ở lần khởi động kế tiếp. Nếu đang mở sẵn, hãy thoát rồi mở lại.
E.Các cách cài khác
Chỉ cài plugin vào Claude Code (không thêm file vào dự án). Gõ trong Claude Code, cần phiên bản 2.1.287 trở lên:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/rufloTừ terminal, với Claude Code 2.1.292 trở lên:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloĐường plugin nhẹ hơn: không thêm file vào workspace, không cài hook. README mô tả đây là cách thử từng plugin mà không cam kết cài đủ bộ. Muốn chạy đúng như tài liệu thì chọn npx ruflo@latest init.
Codex hoặc ứng dụng MCP khác. Cấu hình lệnh (command) là npx và đối số (arguments) là:
["-y", "ruflo@latest", "mcp", "start"]Tương đương lệnh npx -y ruflo@latest mcp start.
Chỉ dùng terminal. Bảng điều khiển chạy độc lập được, không cần Claude Code:
npx ruflo tuiThêm --plain để in ra một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Theo README, cách kiểm tra là:
- Chạy
npx ruflo@latest initxong, bạn thấy thư mục.claude/và.claude-flow/cùng fileCLAUDE.mdtrong dự án. - Mở lại Claude Code trong thư mục đó, rồi gõ
/ruflo. Nếu đã càiruflo-console, bảng điều khiển sẽ hiện ra. - Với đường plugin, gõ
/pluginvà xem plugin có nằm trong dòng "active mods" không.
Ngoài ra, bạn có thể giao một việc thật (xem phần dưới). Nếu Claude Code bắt đầu điều phối agent, vậy là hệ thống đã nhận cấu hình. README chưa mô tả chính xác dòng chữ kết quả khi thành công, nên mình không đoán thêm.
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 nêu trong README.
A.Dev mới nhận một repo lạ và cần biết chỗ nào dễ hỏng
Bạn vừa nhận một dự án cũ, không ai giải thích. Mở Claude Code trong thư mục đó sau khi đã init, rồi dán đúng câu mẫu của README:
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: Claude Code điều phối agent để tìm module rủi ro nhất, viết test cho nó và tóm tắt các thay đổi. Hãy đọc kỹ phần tóm tắt và chạy lại test trước khi giữ thay đổi.
Bạn không cần học hết hàng trăm công cụ. Cài xong, cứ giao việc thật cho Claude Code như bình thường.
Ông T
B.Người làm sản phẩm muốn giao việc và có chỗ theo dõi
Bạn không muốn đọc từng dòng log mà chỉ muốn thấy tiến độ. Cài ruflo-console, mở /ruflo, vào Settings → Claude control và chọn write + ask. Sau đó nói với Claude: "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 trong console. Kiểm tra mục Missions có mục tiêu mới và mục Overview ghi lại hành động. README nhắc: tạo mission không có nghĩa là tính năng đã được làm xong. Nếu muốn dừng, bấm Take back control để tạm ngưng các công cụ console của Claude.
C.Chủ dự án muốn kiểm soát chi phí token
Chạy agent nhiều thì token tăng. Plugin ruflo-cost-tracker theo README giúp theo dõi lượng token dùng, đặt ngân sách và nhận cảnh báo chi phí. Bạn cài nó từ kho plugin bằng lệnh /plugin install theo mẫu ruflo-cost-tracker@ruflo, tương tự các plugin khác. Mình dựa vào mô tả một dòng trong README, nên hãy xem hướng dẫn riêng của plugin trong repo trước khi dựa vào nó để cắt chi phí thật.
D.Nhóm dùng Codex hoặc công cụ MCP khác
Nếu nhóm bạn không dùng Claude Code, đăng ký MCP server của Ruflo vào ứng dụng của bạn: lệnh npx, đối số ["-y", "ruflo@latest", "mcp", "start"]. Bạn có được các công cụ của Ruflo mà không cần chạy init cho dự án. README nói Codex và MCP client khác dùng được theo cách này.
VI.Lỗi hay gặp và cách xử lý
Tư liệu không có mục xử lý sự cố riêng. Dưới đây là các tình huống rất dễ gặp với loại công cụ này, kèm cách xử lý an toàn.
A.Lệnh npx báo lỗi hoặc không chạy
Thường do Node cũ. Repo yêu cầu Node 20 trở lên. Chạy node --version, nếu thấp hơn thì nâng cấp Node rồi chạy lại npx ruflo@latest init.
B.Chạy init nhưng Claude Code không có gì mới
Lý do hay gặp: bạn mở Claude Code ở thư mục khác, hoặc chưa khởi động lại. README nói Claude Code nạp cấu hình ở lần khởi động kế tiếp. Hãy thoát, mở lại đúng thư mục đã chạy init.
C.Lệnh /plugin không nhận hoặc cài plugin thất bại
Đường plugin cần Claude Code 2.1.287 trở lên (lệnh terminal cần 2.1.292 trở lên). Nếu bản của bạn cũ hơn, hãy cập nhật Claude Code hoặc chuyển sang cách npx ruflo@latest init. Sau khi cài, nhớ gõ /reload-plugins.
D.Bị trùng plugin hai lần
README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow: chỉ nên cài từ một marketplace, vì cài từ cả hai thì mod và lệnh sẽ nạp hai lần. Hãy chọn một nguồn.
E.Hành động bị từ chối khi để Claude điều khiển console
Đây là cơ chế an toàn, không phải lỗi. Mặc định là quyền read + ask. Hành động vượt quá quyền bạn cấp sẽ bị từ chối. Các hành động mạng, tốn tiền hoặc phá huỷ luôn cần bạn xác nhận, kể cả ở chế độ auto. Nếu cần, hãy nâng quyền từng bước, và không bật auto khi chưa hiểu rõ.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Giấy phép MIT. Hỗ trợ cả Claude Code lẫn Codex. Có nhiều lựa chọn cài (đầy đủ, plugin, MCP, terminal). Console có cơ chế cấp quyền rõ ràng: read, write, manage, full, kèm ask hoặc auto. Dự án vẫn được cập nhật.
Giới hạn. Hệ thống rất rộng (48 plugin, hàng trăm công cụ), nên người mới dễ choáng. README tự thừa nhận phần "tự học" mới là mô hình khái niệm, và các đoạn demo dùng dữ liệu mẫu, không phải bằng chứng hoàn thành công việc thật. Lệnh init thêm khá nhiều file vào dự án. Plugin chạy với quyền tài khoản của bạn và không bị cô lập. Chạy nhiều agent cũng có thể tốn token hơn dùng một agent.
Khi nên chọn cách khác. Nếu bạn chỉ cần Claude Code làm vài việc nhỏ, không cần nhóm agent hay bộ nhớ, thì cứ dùng Claude Code thuần. Nếu không muốn thêm file vào dự án, hãy thử đường plugin trước. Còn nếu muốn trải nghiệm đủ bộ như tài liệu mô tả, hãy chạy npx ruflo@latest init trong một thư mục thử trước, giao một việc nhỏ, rồi mới áp dụng cho dự án thật.
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 Ruflo chạy quanh Claude Code hoặc Codex, và các dịch vụ AI đó có thể tính phí riêng theo tài khoản của bạn. Tư liệu chưa nêu chi tiết về chi phí.
Ruflo cần phiên bản Node nào?
File package.json yêu cầu Node từ 20.0.0 trở lên. Nếu máy bạn dùng bản cũ hơn, hãy nâng cấp Node trước khi chạy lệnh cài.
Cài Ruflo bằng lệnh nào?
Trong thư mục dự án, chạy `npx ruflo@latest init`, rồi mở lại Claude Code trong cùng thư mục. Nếu chỉ muốn plugin và không thêm file vào dự án, dùng `/plugin marketplace add ruvnet/ruflo` rồi `/plugin install ruflo-core@ruflo` trong Claude Code.
Dùng được với Codex hoặc công cụ không phải Claude Code không?
Có. README nói Codex và các MCP client khác dùng được bằng cách cấu hình lệnh `npx` với đối số `["-y", "ruflo@latest", "mcp", "start"]`. Bạn không cần chạy init cho dự án theo cách này.
Chạy được trên Windows không, có cần GPU không?
Tư liệu chưa nói rõ về hệ điều hành hỗ trợ hay yêu cầu GPU. Điều chắc chắn là cần Node 20 trở lên. Bạn nên xem README và thư mục docs trong repo, hoặc thử trong một thư mục tạm trước.
Ruflo có tự ý làm gì nguy hiểm không?
README mô tả bảng điều khiển có cấp quyền read, write, manage, full với chế độ ask hoặc auto. Mặc định là read + ask. Các hành động mạng, tốn tiền hoặc phá huỷ vẫn cần xác nhận ngay cả khi để auto. README cũng nhắc plugin chạy với quyền tài khoản của bạn và không bị cô lập, nên hãy đọc mã trước khi cài.
Khác gì dùng Claude Code thuần?
Theo README, Ruflo thêm các agent chuyên biệt, nhóm agent phối hợp, bộ nhớ qua các phiên, hook tự động và MCP server vào Claude Code. Nếu bạn chỉ cần việc nhỏ lẻ, Claude Code thuần có thể đã đủ. Tư liệu không có so sánh chi tiết hơn với công cụ khác.


