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”: bộ khung giúp Claude Code, Codex hoặc client MCP khác có thêm agent chuyên biệt, bộ nhớ dài hạn và khả năng chia việc theo nhóm. Bạn dùng nó để giao việc lớn cho nhiều agent phối hợp thay vì một cuộc trò chuyện đơn lẻ. Cài đặt khá dễ: chỉ cần Node 20 trở lên và chạy một lệnh npx trong thư mục dự án.
Ruflo là một “agent harness” mã nguồn mở, tức là lớp bộ khung bọc quanh Claude Code và Codex để các AI này làm việc có tổ chức hơn. Model chỉ biết viết chữ. Còn harness cho nó công cụ, bộ nhớ, vòng lặp và các giới hạn an toàn để nó làm được việc thật. Ruflo chính là phần harness đó, và nó có từ thời còn mang tên Claude Flow.
Vấn đề nó giải quyết khá quen thuộc. Khi giao một việc lớn cho Claude Code, bạn thường phải tự chia nhỏ, tự nhắc lại bối cảnh ở mỗi phiên, và tự kiểm tra kết quả. Ruflo thêm vào dự án của bạn các agent chuyên biệt, bộ nhớ nhớ qua nhiều phiên, hook tự định tuyến công việc và một MCP server. Nhờ vậy nhiều agent có thể phối hợp thành “swarm” (một đàn agent cùng làm một nhiệm vụ).
Repo này dành cho lập trình viên đang dùng Claude Code hoặc Codex hằng ngày, và cho người làm kỹ thuật muốn thử mô hình “đội AI”. Điểm đáng giá nhất là bạn không cần học hết hàng trăm công cụ. README nói rõ: sau khi chạy init, bạn cứ dùng Claude Code như bình thường, phần hook sẽ tự điều phối ở phía sau. Hiện repo có khoảng 81.600 sao và khoảng 9.600 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à lớp điều phối bọc quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server vào dự án chỉ với một lệnh npx.
I.Ruflo làm được gì
Theo README, Ruflo là lớp thực thi bọc quanh Claude Code và Codex. Dưới đây là những phần bạn dễ cảm nhận nhất.
- Nhiều agent chuyên biệt và swarm. README nói có hơn 100 agent chuyên biệt (ở bảng so sánh ghi 98 agent), cùng các lệnh và skill đi kèm. Lợi ích thực tế: bạn giao một việc như “review repo này”, và các agent chia nhau tìm chỗ rủi ro, viết test, tổng kết thay đổi.
- Bộ nhớ tự học. Agent nhớ lại kinh nghiệm qua các phiên làm việc. README có lưu ý rằng phần tìm kiếm vector cục bộ có thể chạy mà không cần LLM, nhưng vẫn cần embedding và các module học được cấu hình.
- Hook tự định tuyến. Sau khi cài, hook tự chọn cách xử lý nhiệm vụ và học từ những mẫu làm việc thành công. Bạn không phải gọi tay từng công cụ.
- MCP server. Codex và các client MCP khác đều trỏ vào được, nên không chỉ riêng Claude Code mới dùng được.
- Federation. Agent trên các máy khác nhau có thể trao đổi với nhau mà README nói là không làm rò dữ liệu. Phần này dành cho người dùng nâng cao.
- Bảng điều khiển (console). Một “buồng lái” ngay cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí, xem lại log và so sánh các lần chạy. Mở bằng lệnh
/ruflo. - Hệ plugin. README liệt kê 48 plugin, chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps… Ví dụ có plugin sinh test tự động, plugin theo dõi chi phí token, plugin quét lỗ hổng và plugin chống prompt injection.
II.Cần chuẩn bị gì
Tư liệu nói khá ít về yêu cầu, nên mình chỉ liệt kê những gì có ghi:
- Node.js từ phiên bản 20 trở lên. File
package.jsoncủa repo yêu cầu>=20.0.0. Đây cũng là điều kiện để chạy được lệnhnpx. - Claude Code nếu bạn muốn dùng đường cài đặt vào dự án. Riêng đường cài bằng plugin thì README yêu cầu Claude Code từ 2.1.287 trở lên. Lệnh cài plugin từ terminal cần 2.1.292 trở lên.
- Codex hoặc client MCP khác nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy lệnh
init.
Tư liệu không nói rõ về hệ điều hành, API key hay phần cứng riêng. Vì vậy mình không khẳng định gì thêm. Nếu cần biết chi tiết, bạn xem README.md, CLAUDE.md và thư mục docs/ trong repo.
III.Cài đặt từng bước
- Mở terminal đúng chỗVào thư mục dự án mà bạn muốn thêm Ruflo
- Chạy initMột lệnh npx thêm agent, hook, bộ nhớ và MCP server vào dự án
- Khởi động lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc thậtDán một câu lệnh mẫu để thử swarm
- (Tuỳ chọn) Mở consoleGõ /ruflo để xem bảng điều khiển
A.Mở terminal trong thư mục dự án
Đây là chỗ người mới hay vấp nhất. 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. Nếu chưa có dự án, hãy tạo một thư mục thử nghiệm riêng để khỏi làm rối thư mục quan trọng.
cd duong-dan/den/du-an-cua-banLệnh trên chỉ là cd thông thường. Bạn thay phần sau bằng đường dẫn thật của dự án.
B.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initnpx tải và chạy Ruflo bản mới nhất mà không cần cài toàn cục. Lệnh init thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh trong README, cách này tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và file cài đặt trong dự án.
Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh sau:
npx ruflo@latest init wizardC.Khởi động lại Claude Code
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thành phần mới ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn một phiên, hãy đóng rồi mở lại.
D.Cách khác: chỉ cài plugin cho Claude Code
Cách này không thêm file nào vào dự án. README ghi rõ cần Claude Code 2.1.287 trở lên. Bạn chạy các dòng sau bên trong Claude Code (không phải trong 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
/rufloNếu muốn cài từ terminal, README ghi lệnh sau, dùng được trên Claude Code 2.1.292 trở lên:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloMod chạy với đúng quyền tài khoản của bạn và không bị cô lập (sandbox). README khuyên đọc mã của mod trước khi cài. Hãy làm vậy, nhất là khi bạn dùng máy công việc.
E.Cách khác: dùng với Codex hoặc client MCP khác
Bạn không cần thiết lập dự án. Chỉ cần cấu hình client MCP với command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]Nói cách khác, client sẽ chạy npx -y ruflo@latest mcp start. Cấu hình này đặt ở đâu thì tuỳ từng client, bạn xem tài liệu của client đó.
F.Cách khác: chạy console ngay trong terminal
Console chạy được độc lập, 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, dấu hiệu thành công khá đơn giản:
- Lệnh
npx ruflo@latest initchạy xong mà không báo lỗi, và thư mục dự án có thêm các mục như.claude/vàCLAUDE.md. - Bạn khởi động lại Claude Code trong thư mục đó, rồi gõ
/ruflođể mở bảng điều khiển. - Nếu cài bằng plugin, mở
/pluginvà xem các mod có hiện trong dòng “active mods” hay không. - Thử một việc thật, ví dụ câu lệnh mẫu ở phần dưới, và xem Claude Code có chia việc cho agent hay không.
Nếu chạy npx ruflo tui mà thấy giao diện hiện ra thì phần console đã hoạt động. README chưa mô tả chính xác dòng chữ mong đợi trong terminal khi init thành công, nên mình không đưa ra thông báo cụ thể.
V.Dùng vào việc thật
Dưới đây là vài tình huống bám đúng những gì README mô tả.
A.Dev nhận một repo lạ và cần review nhanh
Bạn vừa nhận một dự án cũ chưa ai nhớ rõ. Bạn chạy npx ruflo@latest init trong thư mục đó, mở lại Claude Code 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.Claude Code sẽ dùng swarm để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn nhận lại một bản tổng kết để đọc và kiểm tra, thay vì phải tự lần từng file.
Model chỉ viết, còn harness mới là thứ cho nó công cụ, bộ nhớ và giới hạn để làm được việc thật.
Ông T
B.Người dùng muốn theo dõi chi phí và tiến độ
Bạn lo AI chạy tốn token mà không biết. Bạn cài ruflo-console rồi gõ /ruflo. Bảng điều khiển cho xem workflow, agent, model, token và chi phí ngay cạnh Claude Code. README còn có plugin ruflo-cost-tracker để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí. Kết quả là bạn thấy được cuộc chạy tốn bao nhiêu trước khi nó thành một con số bất ngờ.
C.Giao quyền cho Claude điều khiển console, nhưng có giới hạn
README mô tả một kịch bản thử an toàn. Bạn mở /ruflo, vào Settings → Claude control và chọn mức write + ask. Sau đó bạn nhờ:
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, còn bạn xác nhận hành động tạo. Bạn kiểm tra lại ở Missions và Overview. README lưu ý: tạo một 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 và các lệnh sau đó của Claude sẽ bị từ chối. Mức mặc định hiện là read + ask. Các hành động liên quan mạng, chi tiêu hoặc xoá luôn cần bạn xác nhận, kể cả ở chế độ auto.
D.Người dùng 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 client với command npx và arguments -y ruflo@latest mcp start như phần cài đặt ở trên. Từ đó client gọi được các công cụ của Ruflo qua MCP, ví dụ bộ nhớ và điều phối swarm. README nói tổng cộng có hàng trăm công cụ MCP, nhưng bạn không cần học hết, cứ để agent chọn.
VI.Lỗi hay gặp và cách xử lý
Một số lỗi dưới đây là suy luận từ cách công cụ hoạt động. README không liệt kê chúng thành mục riêng.
npxbáo lỗi hoặc không chạy. Rất có thể Node quá cũ. Repo yêu cầu Node từ 20 trở lên, nên hãy kiểm tra phiên bản Node và nâng cấp nếu cần.- Cài 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 kế tiếp. Hãy đóng hẳn và mở lại trong đúng thư mục dự án. Với plugin, chạy thêm
/reload-plugins. - Lệnh
/pluginkhông nhận. Đường plugin cần Claude Code từ 2.1.287 trở lên. Hãy cập nhật Claude Code trước. - Không biết file lạ trong dự án từ đâu ra. Đó là do
initthêm.claude/,.claude-flow/,CLAUDE.mdvà các file liên quan. Hãy thử trên một thư mục riêng trước. Nếu không muốn thêm file vào dự án, dùng đường plugin hoặc đường MCP. - Cài trùng một plugin từ hai marketplace. README cảnh báo với một số plugin bên ngoài: nếu bật từ cả hai nơi, mod và lệnh sẽ nạp hai lần. Chỉ cài từ một nguồn.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh, chỉ một lệnh cho đường đầy đủ. Dùng được với cả Claude Code lẫn Codex và client MCP. Có bảng điều khiển để nhìn thấy agent đang làm gì. Có cơ chế giới hạn quyền cho Claude khi điều khiển console. Giấy phép MIT, cộng đồng lớn và repo vẫn được cập nhật.
Giới hạn. Hệ thống rất lớn: hàng chục plugin, hàng trăm công cụ, nhiều khái niệm như swarm, federation, bộ nhớ vector. Người mới dễ bị ngợp, nên hãy bắt đầu từ một việc nhỏ. README tự thừa nhận vài chỗ chỉ là sơ đồ khái niệm, và các đoạn demo dùng dữ liệu mẫu nên không phải bằng chứng cho việc swarm đã làm xong việc thật. Đường init thêm khá nhiều file vào dự án. Mod chạy với quyền của bạn, nên cần đọc mã trước khi cài. Về chi phí gọi model và các điều kiện khác, tư liệu mình có chưa nói rõ, bạn cần tự xem xét tài khoản và gói dịch vụ đang dùng.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời một câu hỏi hay sửa một file nhỏ, việc thêm cả một harness là thừa. Nếu bạn cần nhẹ nhàng và không muốn file lạ trong dự án, hãy thử đường plugin trước, hoặc chỉ cài một plugin lẻ. Còn nếu bạn hay giao việc lớn, nhiều bước, lặp lại nhiều lần và muốn có bộ nhớ cùng bảng theo dõi, Ruflo đáng để thử trên một dự án nhỏ trước.
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 dùng mã nguồn được. Tuy nhiên tư liệu mình có chưa nói gì về chi phí gọi model phía sau. Phần này phụ thuộc vào tài khoản Claude Code, Codex hoặc nhà cung cấp mà bạn đang dùng.
Cài Ruflo cần những gì?
Cần Node.js từ phiên bản 20 trở lên, vì file package.json yêu cầu như vậy. Nếu dùng đường plugin thì cần Claude Code từ 2.1.287 trở lên. README không nói rõ yêu cầu về phần cứng hay API key riêng.
Ruflo cài bằng lệnh nào?
Trong thư mục dự án, bạn chạy npx ruflo@latest init rồi mở lại Claude Code. Nếu dùng Codex hay client MCP khác, hãy cấu hình command npx với arguments -y, ruflo@latest, mcp, start. Cũng có đường cài plugin ngay trong Claude Code, không thêm file nào vào dự án.
Ruflo có chạy được trên Windows không?
Tư liệu mình có không nói rõ về hệ điều hành. Lệnh cài chỉ cần Node và npx nên về nguyên tắc chạy trong terminal có Node, nhưng chưa có thông tin chính thức. Bạn nên thử trên một thư mục thử nghiệm trước.
Ruflo có làm lộ dữ liệu dự án của tôi không?
README nhấn mạnh các lớp bảo vệ như giới hạn quyền khi Claude điều khiển console, và hành động liên quan mạng, chi tiêu hay xoá luôn cần xác nhận. Phần mod thì chạy với quyền tài khoản của bạn và không bị sandbox, nên README khuyên đọc mã trước khi cài. Tư liệu chưa mô tả chi tiết toàn bộ luồng dữ liệu.
Ruflo khác gì dùng Claude Code thông thường?
Claude Code vẫn là nơi bạn làm việc. Ruflo thêm lớp bao quanh gồm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook tự định tuyến và bảng điều khiển. Bạn vẫn dùng Claude Code bình thường, phần phối hợp chạy ngầm.
Tôi chưa quen AI agent thì có dùng được không?
README nói bạn không cần học hết các công cụ và lệnh. Chỉ cần chạy init rồi giao việc cho Claude Code như bình thường. Tuy vậy hệ thống khá lớn, nên hãy bắt đầu bằng một dự án nhỏ và một nhiệm vụ cụ thể.


