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 "harness" bao quanh Claude Code và Codex. Nó thêm các agent chuyên biệt, bộ nhớ qua nhiều phiên làm việc, hook tự động và MCP server vào dự án của bạn. Cài chỉ cần một lệnh `npx ruflo@latest init` và cần Node 20 trở lên, nên người mới cũng làm được.
Ruflo là một bộ khung (harness) bao quanh Claude Code và Codex. Nó giúp các công cụ lập trình bằng AI này làm việc theo nhóm, nhớ được việc cũ và có thêm "đồ nghề" để làm việc thật. Trước đây dự án tên là Claude Flow, hiện có khoảng 81.600 sao và khoảng 9.600 fork trên GitHub, giấy phép MIT.
Hãy hình dung thế này: mô hình AI là người viết, còn harness là cái bàn làm việc xung quanh. Bàn làm việc ấy gồm công cụ, bộ nhớ, vòng lặp kiểm tra và các giới hạn an toàn. Ruflo chính là cái bàn đó. Sau khi cài, bạn vẫn mở Claude Code và giao việc như bình thường. Phần chia việc cho nhiều agent, ghi nhớ kinh nghiệm và định tuyến tác vụ diễn ra ở phía sau.
Repo hợp với lập trình viên mới, người làm kỹ thuật ở công ty nhỏ, hoặc người đã quen Claude Code và muốn nó làm được việc lớn hơn. Điểm đáng giá nhất là bạn không phải học hết hàng trăm công cụ. README nói rõ: sau init, bạn cứ dùng Claude Code như thường.
ruvnet/ruflo
Ruflo là bộ khung bao quanh Claude Code và Codex, thêm 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ì
README giới thiệu rất nhiều thứ. Dưới đây là những phần dễ hiểu và có ích nhất với người mới.
- Nhiều agent chuyên biệt. Cài đầy đủ bằng
initsẽ có 98 agent, hơn 60 lệnh và 30 skill. Thay vì một AI làm tất cả, bạn có thể nhờ cả một "đội" chia nhau việc: người tìm lỗi, người viết test, người tổng hợp. - Swarm (bầy agent) phối hợp. Các agent tự tổ chức để chia việc. Bạn chỉ cần mô tả mục tiêu, ví dụ "review repo này".
- Bộ nhớ qua nhiều phiên. Agent lưu lại kinh nghiệm và nhớ giữa các lần làm việc. Nhờ đó lần sau bạn đỡ phải giải thích lại từ đầu. README lưu ý đây là mô hình học theo khái niệm. Một số phần cần cấu hình embedding và các module học tương ứng.
- Hook tự động. Hook định tuyến tác vụ và học từ những mẫu thành công mà bạn không phải ra lệnh từng bước.
- MCP server. Claude Code, Codex hoặc client MCP khác đều có thể gọi các công cụ của Ruflo.
- Bảng điều khiển (console). Một "buồng lái" cạnh Claude Code để theo dõi workflow, agent, mô hình, token và chi phí. Bạn cũng xem được log, tìm kiếm, phát lại và so sánh các lần chạy.
- Kiểm soát quyền cho Claude. Trong Settings → Claude control, bạn chọn mức
read,write,managehoặcfull, cùng chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các hành động liên quan mạng, chi tiền hoặc xoá vẫn phải xác nhận ngay cả khi đểauto. - 48 plugin cài riêng. Gồm swarm, bộ nhớ RAG, sinh test, quét bảo mật, theo dõi chi phí, tài liệu tự động, và nhiều thứ khác. Bạn cài cái nào dùng cái đó.
- Federation. Agent trên các máy khác nhau có thể trao đổi với nhau. Phần này nâng cao, người mới chưa cần đụng tới.
II.Cần chuẩn bị gì
Tư liệu nêu những điều kiện sau:
- Node.js từ phiên bản 20.0.0 trở lên. Đây là yêu cầu trong
package.json. Ruflo chạy quanpx, nên máy bạn cần có Node và npm. - Claude Code nếu bạn muốn dùng theo cách chính. Với đường cài chỉ bằng plugin, README yêu cầu Claude Code 2.1.287 trở lên. Nếu muốn cài plugin bằng lệnh từ terminal thì cầ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 hiện tại. - Codex hoặc client MCP khác là tuỳ chọn, nếu bạn không dùng Claude Code.
Tư liệu không nói rõ về yêu cầu GPU, dung lượng ổ đĩa hay hệ điều hành cụ thể. README cũng không nói cần API key riêng cho Ruflo. Tài khoản và quyền dùng Claude Code hay Codex là phần của các công cụ đó. Phần "học" và embedding thì README bảo là cần cấu hình thêm, nên hãy xem trong thư mục docs/ nếu bạn muốn dùng sâu.
III.Cài đặt từng bước
README có ba đường cài. Đường đơn giản nhất và được khuyến nghị cho dùng thật là npx ruflo@latest init. Hai đường còn lại nhẹ hơn.
- Kiểm tra NodeChắc chắn máy có Node 20 trở lên
- Mở terminal trong dự ánVào đúng thư mục dự án của bạn
- Chạy initChạy một lệnh npx để thêm agent, hook, bộ nhớ và MCP server
- Mở Claude CodeKhởi động lại Claude Code trong cùng thư mục
- Giao một việc thậtThử một câu lệnh mẫu để xem Ruflo làm gì
A.Kiểm tra Node
Mở terminal (trên Windows là PowerShell hoặc Terminal, trên macOS/Linux là Terminal) và chạy:
node --versionNếu số hiện ra nhỏ hơn 20, bạn cần cập nhật Node trước. Đây là chỗ người mới hay vấp: lệnh npx chạy được nhưng Node cũ sẽ gây lỗi lạ phía sau.
B.Mở terminal đúng thư mục dự án
Bạn cần đứng trong thư mục dự án mà bạn muốn Ruflo hỗ trợ. Nếu chưa có dự án và chỉ muốn thử, hãy tạo một thư mục trống rồi vào đó. Đừng chạy trong thư mục quan trọng mà bạn chưa sao lưu, vì init sẽ thêm file vào đó.
cd ten-thu-muc-du-an-cua-banC.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo README, bản cài đầy đủ tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings. Bạn nên chạy trên một nhánh Git riêng để dễ xem và hoàn tác.
Nếu muốn cài theo hướng dẫn từng câu hỏi, README có lệnh sau:
npx ruflo@latest init wizardD.Mở lại Claude Code
Claude Code sẽ nhận các thứ vừa thêm vào ở lần khởi động tiếp theo. Vì vậy hãy đóng và mở lại Claude Code trong cùng thư mục. Sau đó bạn có thể gõ /ruflo để mở bảng điều khiển.
E.Đường cài khác: chỉ cài plugin trong Claude Code
Nếu bạn không muốn thêm file nào vào dự án, README có cách cài plugin, "zero file" trong workspace. Chạy các lệnh sau bên trong Claude Code:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/rufloNế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/rufloCác "mod" chạy với đúng quyền tài khoản của bạn và không bị cô lập trong sandbox. README khuyên đọc code của mod trước khi cài.
Đường plugin chỉ cho bạn lệnh gạch chéo và một số skill, agent. Nó không cài hook. Muốn có đủ vòng làm việc đầy đủ thì dùng init.
F.Đường cài khác: Codex hoặc client MCP
Nếu bạn dùng Codex hoặc công cụ khác hỗ trợ MCP, README hướng dẫn cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Tương đương dòng lệnh:
npx -y ruflo@latest mcp startCách điền cấu hình cụ thể tuỳ từng client. README không nêu chi tiết từng client, nên bạn cần xem tài liệu của chính client đó.
G.Chạy bảng điều khiển ngoài Claude Code
Bảng điều khiển còn chạy được độc lập trong terminal:
npx ruflo tuiThêm --plain để in ra một khung hình duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh "kiểm tra" chính thức sau init. Dưới đây là những dấu hiệu theo đúng tư liệu:
- Sau
npx ruflo@latest init, trong thư mục dự án xuất hiện các thư mục và file như.claude/,.claude-flow/vàCLAUDE.md. - Khởi động lại Claude Code trong thư mục đó, rồi gõ
/ruflo. Nếu bảng điều khiển hiện ra thì bạn đã cài đúng. - Với đường plugin, gõ
/pluginvà xem các plugin có hiện trong dòng "active mods" không. - Với đường MCP, thử
npx -y ruflo@latest mcp starttrong terminal. Client của bạn cần nhận được server MCP này.
Muốn kiểm tra thật nhất, hãy giao một việc nhỏ như ở phần tiếp theo và xem Claude Code phản hồi ra sao.
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ế phụ thuộc vào dự án và mô hình bạn dùng.
A.Rà soát một dự án thừa kế
Bạn là lập trình viên mới nhận một repo cũ và không biết chỗ nào dễ hỏng. Sau khi chạy init và mở lại Claude Code, bạn dán câu lệnh mẫu có trong README:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.Câu này nhờ cả bầy agent tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn nhận được một bản tóm tắt cùng các file test mới. Hãy chạy test và đọc kỹ trước khi giữ lại. AI viết test không có nghĩa test luôn đúng.
B.Theo dõi chi phí và việc đang chạy
Bạn là chủ một nhóm nhỏ, dùng Claude Code mỗi ngày và hay giật mình với hoá đơn token. Cài ruflo-console và gõ /ruflo. README mô tả bảng điều khiển theo dõi workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Bạn còn mở log của từng agent để biết lần chạy nào hỏng và vì sao. Nếu cần kiểm soát chặt hơn, plugin ruflo-cost-tracker có chức năng theo dõi token, đặt ngân sách và cảnh báo chi phí.
Bạn vẫn viết code như bình thường — Ruflo lo phần phối hợp ở phía sau.
Ông T
C.Cho Claude tự tạo mission, bạn giữ quyền duyệt
README có một bài thực hành an toàn. Bạn mở /ruflo, vào Settings → Claude control và chọn write + ask. Sau đó bạn nhắn:
Create a mission to add a dark mode toggle. Show me the mission and its status.Claude sẽ mở mục Missions và đặt mục tiêu. Bạn xác nhận hành động tạo trong console. Kết quả là mục tiêu xuất hiện trong Missions và Overview ghi lại hành động. README lưu ý: tạo mission không có nghĩa tính năng đã được viết. Nếu muốn dừng, bấm Take back control và Claude sẽ bị từ chối các lệnh tiếp theo cho đến khi bạn trả quyền lại.
D.Dùng Ruflo từ Codex hoặc công cụ MCP khác
Bạn không dùng Claude Code mà dùng Codex. Bạn cấu hình command npx với tham số ["-y", "ruflo@latest", "mcp", "start"] trong client. Các công cụ của Ruflo như bộ nhớ và điều phối swarm sẽ khả dụng qua MCP. README không mô tả chi tiết từng client, nên bạn nên thử trên dự án nhỏ trước.
VI.Lỗi hay gặp và cách xử lý
Tư liệu không có mục xử lý sự cố. Dưới đây là những lỗi rất dễ xảy ra với loại công cụ này.
Lỗi về phiên bản Node. package.json yêu cầu Node từ 20 trở lên. Nếu chạy npx báo lỗi lạ hoặc cú pháp không hiểu, hãy kiểm tra bằng node --version và nâng Node lên.
Cài xong mà Claude Code không thấy gì. README nói Claude Code chỉ nhận các thứ mới ở lần khởi động tiếp theo. Hãy đóng hẳn rồi mở lại Claude Code trong đúng thư mục đã chạy init. Với plugin, chạy thêm /reload-plugins.
Lệnh plugin không được nhận. Các lệnh /plugin ... cần Claude Code từ 2.1.287 trở lên, còn lệnh claude plugin install từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code nếu phiên bản của bạn cũ hơn.
Cài trùng plugin từ hai nơi. Với một số plugin bên ngoài như agentdb, agentic-flow hoặc agentic-qe-fleet, README nhắc: chỉ cài từ một marketplace, vì cài từ cả hai nơi thì mod và lệnh sẽ tải hai lần. Hãy gỡ bản thừa.
Claude làm quá tay hoặc bị từ chối hành động. Nếu Claude bị từ chối thao tác, có thể mức quyền trong Claude control đang quá thấp (mặc định là read + ask). Hãy tăng từng nấc, ưu tiên giữ chế độ ask. Đừng bật full + auto ngay khi chưa hiểu rõ.
Không biết mình đã cài đường nào. Đường plugin không thêm file vào dự án, còn init thì có. Nếu bạn thấy thư mục .claude/ và .claude-flow/, bạn đang ở đường init. Muốn gỡ, hãy xem tài liệu trong repo hoặc quay về nhánh Git sạch trước khi chạy init.
VII.Có nên dùng không
Điểm mạnh. Cài đặt rất nhanh, chỉ một lệnh npx. Có hai đường cài để bạn chọn mức cam kết. Hệ sinh thái rộng: agent, bộ nhớ, bảng điều khiển, plugin theo nhu cầu. Có cơ chế kiểm soát quyền rõ ràng cho phần Claude điều khiển console. Dự án đang được cập nhật trong vài tháng gần đây và theo giấy phép MIT.
Giới hạn. Hệ thống rất lớn: README nhắc tới 406 công cụ MCP và 61 lệnh CLI, nên dễ gây choáng. May là bạn không cần học hết. README cũng tự nhắc những phần học và bộ nhớ có phụ thuộc vào cấu hình embedding. Bản demo trong README dùng dữ liệu mẫu hoặc phát lại khung hình, không chứng minh việc swarm đã làm xong thật. Tư liệu chưa nói rõ về Windows, GPU hay chi phí vận hành thực tế, nên bạn cần tự thử.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần một trợ lý lập trình đơn giản cho vài file, Claude Code hoặc Codex đứng một mình là đủ. Ruflo đáng thử khi bạn làm việc dài hơi, nhiều bước, cần agent nhớ ngữ cảnh hoặc cần theo dõi chi phí và log. Hãy bắt đầu trên một dự án thử, đọc file nó thêm vào, rồi mới đưa vào dự án quan trọng.
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 bạn được dùng và sửa mã nguồn. Tuy nhiên Ruflo chạy cùng Claude Code hoặc Codex, và chi phí của các dịch vụ đó nằm ngoài repo. Tư liệu không nêu bảng giá cụ thể.
Ruflo khác gì Claude Code?
Claude Code là công cụ lập trình bằng AI. Ruflo là lớp bao quanh nó, theo README gọi là harness, thêm agent chuyên biệt, bộ nhớ, hook và MCP server. Bạn vẫn dùng Claude Code như bình thường, còn Ruflo lo phần điều phối ở phía sau.
Cần cài gì trước khi dùng Ruflo?
Bạn cần Node.js từ phiên bản 20 trở lên và một dự án để chạy lệnh. Nếu cài bằng plugin trong Claude Code, cần Claude Code từ 2.1.287 trở lên. README không nêu thêm yêu cầu khác như GPU hay dung lượng ổ đĩa.
Cài Ruflo có khó không?
Cách đơn giản nhất chỉ là một lệnh: `npx ruflo@latest init` trong thư mục dự án, rồi mở lại Claude Code. Ngoài ra có thêm đường cài plugin và đường cấu hình MCP cho Codex. Nếu muốn được hướng dẫn từng câu hỏi, README có lệnh `npx ruflo@latest init wizard`.
Ruflo chạy được trên Windows không?
Tư liệu không nói rõ về hệ điều hành được hỗ trợ. Vì Ruflo chạy qua Node và `npx`, bạn có thể thử, nhưng chưa có thông tin chính thức về Windows. Hãy xem thư mục docs trong repo hoặc thử trên một dự án nhỏ trước.
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 dùng được, bằng cách cấu hình command `npx` với tham số `["-y", "ruflo@latest", "mcp", "start"]`. Cách điền cụ thể tuỳ từng client và README không nêu chi tiết.
Claude có thể tự làm bất cứ việc gì trong bảng điều khiển không?
Không. Bạn chọn mức quyền `read`, `write`, `manage` hoặc `full`, cùng chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các hành động liên quan mạng, chi tiền hoặc xoá vẫn cần xác nhận, và bạn có thể bấm Take back control để dừng.


