Ruflo: điều phối nhiều 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à bộ khung điều phối agent AI, chạy quanh Claude Code, Codex và các client MCP khác. Nó thêm agent chuyên biệt, bộ nhớ qua các phiên, hooks và bảng điều khiển vào dự án của bạn. Cài 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 "harness" (bộ khung) bao quanh Claude Code và Codex. Hiểu đơn giản: mô hình AI là người viết, còn Ruflo là cái bàn làm việc đầy đủ dụng cụ quanh người đó. Nó thêm công cụ, bộ nhớ, vòng lặp kiểm tra và cơ chế phối hợp nhiều agent để AI làm được việc dài hơi, thay vì chỉ trả lời từng câu.
Repo này dành cho người đã dùng (hoặc định dùng) Claude Code và muốn giao những việc lớn hơn: rà soát cả dự án, viết test, theo dõi chi phí token. Lập trình viên mới cũng dùng được, vì README nói rõ bạn không cần học hết hàng trăm công cụ bên trong. Sau khi cài, bạn cứ dùng Claude Code như bình thường, phần điều phối chạy nền.
Điểm đáng giá nhất là cách cài: một lệnh npx ruflo@latest init trong thư mục dự án là xong. Repo hiện có khoảng 81588 sao và 9608 fork, giấy phép MIT, viết chủ yếu bằng TypeScript và vẫn được cập nhật trong vài tháng gần đây.
ruvnet/ruflo
Ruflo là bộ khung (harness) bao quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, swarm phối hợp và bảng điều khiển, cài bằng một lệnh npx.
I.Ruflo làm được gì
Theo README, Ruflo gom nhiều thứ vào một chỗ. Dưới đây là những ý có giá trị thực tế nhất với người mới.
A.Agent và swarm
Sau khi init, dự án của bạn có sẵn nhiều agent chuyên biệt (README nói khoảng 98 agent ở đường cài CLI, ở phần khác ghi 100+). Các agent có thể chia thành "swarm" để cùng làm một việc: người tìm module rủi ro, người viết test, người tổng hợp. Lợi ích: bạn giao một yêu cầu lớn, không phải tự chia nhỏ từng bước.
B.Bộ nhớ qua các phiên
Ruflo có bộ nhớ để agent nhớ lại kinh nghiệm giữa các lần làm việc, kèm tìm kiếm vector (HNSW, RAG). Hữu ích khi dự án lớn và bạn không muốn giải thích lại bối cảnh mỗi lần mở Claude Code. README lưu ý phần "tự học" hiện là mô hình khái niệm, và cần cấu hình embedding.
C.Hooks tự động định tuyến
Hooks tự chọn agent hợp cho tác vụ và học từ những lần làm thành công. Bạn không cần gọi từng công cụ thủ công.
D.Bảng điều khiển trong Claude Code
Plugin ruflo-console cho bạn một "cockpit" cạnh Claude Code: xem workflow, agent, model, token và chi phí. Bạn mở bằng lệnh /ruflo. Có thể xem log từng lần chạy, tìm kiếm, xem lại và so sánh.
E.Cho Claude điều khiển bảng điều khiển, bạn đặt giới hạn
Trong Settings có mục Claude control với các mức read, write, manage, full và chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask, tức Claude chỉ đọc và hỏi bạn trước. Hành động liên quan mạng, chi tiêu hay phá hủy luôn cần bạn xác nhận, kể cả khi để auto.
F.Hệ plugin
README liệt kê 48 plugin: swarm, theo dõi chi phí (ruflo-cost-tracker), tạo test (ruflo-testgen), quét bảo mật (ruflo-security-audit), tài liệu (ruflo-docs), bộ nhớ (ruflo-agentdb, ruflo-rag-memory)… Bạn chọn cái cần, không bắt buộc lấy hết.
G.Dùng với Codex và client MCP khác
Ngoài Claude Code, Codex và các client MCP khác cũng kết nối được qua một lệnh khởi động MCP server.
II.Cần chuẩn bị gì
Chỉ những gì tư liệu nói:
- Node.js từ 20.0.0 trở lên (theo
package.json). Lệnhnpxđi kèm Node. - Claude Code nếu bạn dùng đường cài bằng plugin: cần phiên bản 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) để chạy
init. Nếu chưa có, tạo thư mục trống cũng được. - Codex hoặc client MCP khác: tùy chọn, nếu bạn muốn dùng ngoài Claude Code.
Tư liệu không nói rõ yêu cầu hệ điều hành, phần cứng hay API key riêng cho Ruflo. Bạn vẫn cần tài khoản/quyền dùng Claude Code (hoặc Codex) như bình thường. Muốn chắc về hệ điều hành, xem README.md và thư mục docs/ trong repo.
Gói npm của dự án có tên khai báo là claude-flow (tên cũ), nhưng README hướng dẫn gọi bằng ruflo. Bạn cứ chép lệnh đúng như trong bài này.
III.Cài đặt từng bước
Ruflo có ba đường cài. Đường chính là npx ruflo@latest init, cho trải nghiệm đầy đủ nhất. Hai đường còn lại nhẹ hơn.
- Kiểm tra NodeĐảm bảo Node từ 20 trở lên
- Mở terminal đúng chỗVào thư mục dự án của bạn
- Chạy initThêm agent, hooks, bộ nhớ, MCP server vào dự án
- Mở lại Claude CodeKhởi động lại trong cùng thư mục để nhận cấu hình
- Giao việc thửDán một yêu cầu thật cho swarm
A.Kiểm tra Node và mở terminal đúng thư mục
Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) rồi đi tới thư mục dự án. Lệnh node --version là lệnh phổ thông để xem phiên bản; bạn cần thấy số từ 20 trở lên.
node --version
cd duong-dan-toi-thu-muc-du-anChỗ người mới hay vấp: chạy init ở sai thư mục. Ruflo ghi file vào thư mục hiện tại, nên hãy chắc bạn đang đứng đúng trong dự án.
B.Chạy lệnh init (đường chính)
npx ruflo@latest initLệnh này thêm agent, hooks, bộ nhớ và MCP server của Ruflo vào dự án. Theo README, nó tạo các thư mục như .claude/, .claude-flow/ và file CLAUDE.md, cùng settings. Vì thế dự án của bạn sẽ có thêm file mới. Nếu dự án quan trọng, nên commit hoặc sao lưu trước.
Muốn cài có hướng dẫn từng câu hỏi, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code
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 tiếp theo. Nếu bạn đang mở sẵn, hãy thoát rồi mở lại.
D.Đường thay thế: chỉ cài plugin trong Claude Code
Đường này không thêm file nào vào dự án. Chạy trong Claude Code (cầ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, trên Claude Code 2.1.292 trở lên, README ghi cách cài một plugin:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloSo sánh nhanh theo README: plugin thì "nhẹ", chủ yếu là lệnh slash và định nghĩa agent, không có hooks. Cài bằng init mới có đủ vòng lặp (agent, lệnh, skill, MCP server, hooks, daemon) và README khuyên dùng cho việc nghiêm túc.
Các "mod" chạy với quyền tài khoản của bạn và không bị cô lập (sandbox). README dặn hãy đọc mã trước khi cài.
E.Đường thay thế: Codex hoặc client MCP khác
Trong phần cấu hình MCP của client, đặt command là npx và arguments là danh sách sau:
["-y", "ruflo@latest", "mcp", "start"]Tương đương dòng lệnh npx -y ruflo@latest mcp start. Nếu bạn dùng Claude Code, hãy dùng init ở trên thay vì cách này.
F.Chạy bảng điều khiển ngoài Claude Code
Bảng điều khiển cũng chạy độc lập trong terminal:
npx ruflo tuiThêm --plain để in một khung hình, hợp khi dùng trong script.
IV.Kiểm tra đã chạy được chưa
Có vài dấu hiệu theo README:
- Sau
init, trong thư mục dự án xuất hiện.claude/,.claude-flow/vàCLAUDE.md. - Mở lại Claude Code rồi gõ
/ruflo: bảng điều khiển hiện ra. - Nếu cài bằng plugin, gõ
/pluginđể xem các mod có nằm trong dòng "active mods" không. - Thử
npx ruflo tuingoài terminal: nếu màn hình bảng điều khiển hiện ra là Node và gói đang chạy ổn.
Tư liệu không nêu một câu lệnh "kiểm tra phiên bản" riêng, nên mình không bịa ra. Nếu muốn kiểm tra sâu hơn, xem thư mục docs/ và hướng dẫn người dùng trong repo.
V.Dùng vào việc thật
A.Dev rà soát một dự án đang chạy
Bối cảnh: bạn vừa nhận một dự án cũ, không rõ chỗ nào dễ hỏng. Sau khi chạy init và mở lại Claude Code, dán đúng prompt 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: 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 đọc phần tóm tắt, rồi tự xem lại diff 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ứ dùng Claude Code như thường, phần điều phối chạy nền.
Ông T
B.Chủ shop làm website tự theo dõi chi phí AI
Bối cảnh: bạn thuê người làm hoặc tự làm web bán hàng bằng Claude Code, và lo tiền token tăng lên mà không biết. Cài ruflo-console bằng đường plugin, mở /ruflo để xem token và chi phí cạnh Claude Code. README cũng có plugin ruflo-cost-tracker để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí. Bạn vẫn là người quyết định có tiếp tục hay không.
C.Người mới thử cho Claude tạo "mission" an toàn
Bối cảnh: bạn muốn thử cho Claude điều khiển bảng điều khiển nhưng sợ mất kiểm soát. Làm theo các bước README gợi ý:
- Cài console, mở
/ruflo, vào Settings → Claude control rồi chọn write + ask. - Nói với Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status."
- Xác nhận hành động tạo khi bảng điều khiển hỏi.
- Kiểm tra mục Missions có mục tiêu mới, và Overview ghi lại hành động.
Kết quả: bạn có một "mission" trong danh sách. README nhấn mạnh tạo mission không có nghĩa tính năng đã được viết xong. Nếu muốn dừng, bấm Take back control.
D.Nhóm nhỏ nối Codex hoặc client MCP khác
Bối cảnh: nhóm bạn dùng Codex thay vì Claude Code. Trong cấu hình MCP của Codex, khai báo command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Codex sẽ gọi được các công cụ MCP của Ruflo mà không cần setup dự án. Muốn thiết lập dự án có hướng dẫn thì chạy npx ruflo@latest init wizard.
VI.Lỗi hay gặp và cách xử lý
A.Claude Code không thấy agent hay lệnh mới
Nguyên nhân thường gặp: Claude Code đang mở từ trước khi chạy init, hoặc mở sai thư mục. Hãy thoát, mở lại trong đúng thư mục dự án. Với plugin, thử /reload-plugins.
B.Lệnh plugin báo không nhận hoặc không có
README yêu cầu Claude Code từ 2.1.287 trở lên (và 2.1.292 cho lệnh claude plugin install ở terminal). Hãy cập nhật Claude Code trước rồi thử lại.
C.Lỗi Node hoặc npx
Node cũ hơn 20 có thể gây lỗi khi chạy. Chạy node --version, nếu thấp hơn thì cài Node mới rồi mở terminal mới.
D.Cài cùng một plugin từ hai nơi
README cảnh báo với plugin ngoài như agentdb hoặc agentic-qe-fleet: chỉ cài từ một marketplace. Cài từ cả hai thì mod và lệnh bị nạp hai lần. Nếu thấy lệnh bị lặp, hãy gỡ một bản.
E.Muốn thử nhưng sợ làm rối dự án
init thêm khá nhiều file vào dự án. Hãy thử trên một thư mục sao chép hoặc nhánh riêng trước. Hoặc dùng đường plugin, vì README nói đường này không thêm file nào vào workspace.
VII.Có nên dùng không
Điểm mạnh: cài rất nhanh bằng một lệnh; có bảng điều khiển để nhìn thấy agent, token và chi phí; có cơ chế phân quyền cho việc Claude điều khiển (mặc định chỉ đọc và hỏi); giấy phép MIT; dự án còn được cập nhật. Hệ sinh thái plugin rộng, bạn chọn phần cần dùng.
Giới hạn: dự án rất lớn (hàng trăm công cụ MCP, hàng chục lệnh), nên người mới dễ choáng nếu muốn khai thác hết. Một số phần như "tự học" README tự ghi là mô hình khái niệm, và các video minh họa dùng dữ liệu mẫu, không phải bằng chứng cho việc swarm đã hoàn thành công việc thật. Đường init thêm nhiều file vào dự án. Các mod không bị cô lập và chạy với quyền của bạn.
Khi nào chọn cách khác: nếu bạn chỉ cần Claude Code trả lời và sửa vài file nhỏ, dùng Claude Code thuần là đủ và gọn hơn. Chỉ nên cài Ruflo khi bạn thực sự cần nhiều agent phối hợp, bộ nhớ lâu dài hoặc theo dõi chi phí. Nếu chỉ muốn thử, hãy bắt đầu bằng đường plugin và thêm dần.
Câu hỏi thường gặp
Ruflo có miễn phí không?
Mã nguồn dùng giấy phép MIT nên bạn dùng tự do. Tuy nhiên Ruflo chạy quanh Claude Code hoặc Codex, nên chi phí dùng các dịch vụ đó vẫn theo tài khoản của bạn. Tư liệu không nêu bảng giá riêng cho Ruflo.
Ruflo khác gì Claude Code thuần?
Claude Code là công cụ viết code; Ruflo là lớp bao quanh nó, thêm agent chuyên biệt, swarm, bộ nhớ, hooks và bảng điều khiển. Sau khi cài, bạn vẫn dùng Claude Code như bình thường, còn Ruflo điều phối ở phía sau.
Cần cài gì trước khi dùng?
Cần Node.js từ 20.0.0 trở lên. Nếu cài bằng plugin thì cần Claude Code bản 2.1.287 trở lên (2.1.292 cho lệnh claude plugin install ở terminal). Tư liệu chưa nêu yêu cầu về GPU hay phần cứng riêng.
Ruflo có chạy trên Windows không?
Tư liệu chưa nói rõ về hệ điều hành được hỗ trợ. Các lệnh chính chỉ là npx, nên về nguyên tắc chạy được nơi có Node 20 trở lên, nhưng bạn nên xem README và thư mục docs trong repo để chắc chắn.
Ruflo có làm tôi mất file của dự án không?
Lệnh init thêm file và thư mục như .claude/, .claude-flow/ và CLAUDE.md vào dự án. Nên sao lưu hoặc dùng nhánh riêng trước khi thử. Nếu không muốn thêm file, README nói đường cài plugin không để lại file nào trong workspace.
Claude có thể tự làm bậy trong bảng điều khiển không?
README nói mặc định hiện là read + ask: Claude chỉ đọc và phải hỏi bạn. Các hành động liên quan mạng, chi tiêu hay phá hủy vẫn cần xác nhận kể cả khi để auto, và bạn có nút Take back control để lấy lại quyền.
Dùng được với Codex không?
Được. README hướng dẫn cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"] trong Codex hoặc client MCP khác, không cần setup dự án.


