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à một agent harness: lớp công cụ bao quanh Claude Code và Codex để nhiều agent phối hợp, nhớ việc qua các phiên và có kiểm soát. Bạn dùng nó để giao việc lớn cho một nhóm agent thay vì một cuộc trò chuyện đơn lẻ. Cài khá dễ vì chỉ cần Node 20 trở lên và một lệnh npx, nhưng bộ tính năng rất rộng nên nên bắt đầu từ việc nhỏ.
ruflo là một “agent harness” — lớp công cụ bao quanh Claude Code và Codex, giúp mô hình AI không chỉ trả lời mà còn có agent chuyên biệt, bộ nhớ, vòng lặp và các chốt kiểm soát để làm việc thật. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, viết chủ yếu bằng TypeScript, giấy phép MIT.
Vấn đề nó giải quyết khá quen thuộc: khi giao một việc lớn cho Claude Code, mọi thứ dồn vào một cuộc trò chuyện, dễ quên bối cảnh, khó chia việc và khó kiểm tra. ruflo thêm vào dự án của bạn các agent, hook (đoạn tự chạy ở các thời điểm nhất định), bộ nhớ và một MCP server, để các agent tự chia nhóm làm việc và học từ những việc đã làm.
Bạn nên đọc tiếp nếu bạn là lập trình viên (kể cả mới) đang dùng Claude Code hoặc Codex và muốn thử làm việc theo kiểu “một đội agent”. Điểm đáng giá nhất: cài chỉ một lệnh npx ruflo@latest init, sau đó bạn cứ dùng Claude Code như bình thường. Hiện repo có khoảng 81.600 sao và 9.600 fork, 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 bao quanh Claude Code và Codex: thêm agent chuyên biệt, bộ nhớ, hook và MCP server vào dự án chỉ bằng một lệnh.
I.ruflo làm được gì
Theo README, bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Sau init, hệ thống hook tự định tuyến việc và phối hợp agent ở phía sau. Dưới đây là những phần bạn sẽ thấy hữu ích nhất.
- Nhóm agent (swarm). Có hơn 100 agent chuyên biệt (bản cài bằng CLI ghi 98 agent). Chúng có thể chia việc, làm song song rồi trả kết quả. Lợi ích: một yêu cầu như “rà soát cả repo” được chia nhỏ thay vì dồn vào một lượt trả lời.
- Bộ nhớ qua nhiều phiên. Agent nhớ kinh nghiệm giữa các lần làm việc, có tìm kiếm theo vector. README nói phần truy xuất 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ấu hình.
- Học từ việc đã làm. Hệ thống ghi nhận mẫu việc thành công để định tuyến lần sau tốt hơn. README gọi đây là vòng học mang tính khái niệm, đừng hiểu là phép màu.
- Bảng điều khiển trong Claude Code (
/ruflo). Bạn xem workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code, mở log của từng lần chạy, tìm kiếm, phát lại và so sánh. - Cho Claude lái nhưng bạn đặt giới hạn. Trong Settings → Claude control, bạn chọn mức quyền
read,write,managehoặcfull, và chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. 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. - Hệ plugin. Có 48 plugin trong marketplace của ruflo (cộng 3 plugin bên ngoài): test tự động, theo dõi chi phí token, quét bảo mật, tài liệu, workflow, liên kết agent giữa các máy (federation)…
- Nhiều “máy khách” khác nhau. Ngoài Claude Code còn có Codex và các MCP client khác; README cũng có lệnh
npx ruflo init --grokcho Grok Build.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu những điều sau, mình không thêm gì ngoài đó:
- Node.js từ phiên bản 20.0.0 trở lên (theo
package.json). Bạn cần cónpxđi kèm Node. - Claude Code nếu bạn dùng cách cài plugin: cần bản 2.1.287 trở lên; lệnh cài plugin từ terminal cần bản 2.1.292 trở lên.
- Một dự án (thư mục) để chạy
inittrong đó. - Codex hoặc MCP client khác nếu bạn không dùng Claude Code.
README chưa nói rõ yêu cầu hệ điều hành, phần cứng hay API key riêng cho từng tính năng. Nếu bạn dùng tính năng cần mô hình hoặc embedding, hãy xem thêm trong thư mục docs/ của repo.
Các “mod” của ruflo 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 đọc mã của chúng trước khi cài. Đây là lưu ý quan trọng nhất của bài này.
III.Cài đặt từng bước
README có ba đường cài. Cách chính là npx ruflo@latest init trong thư mục dự án. Hai cách còn lại là chỉ cài plugin Claude Code, hoặc nối qua MCP cho Codex.
- Mở terminal đúng thư mụcvào thư mục dự án của bạn, kiểm tra đã có Node 20 trở lên
- Chạy initgõ npx ruflo@latest init để 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 một việc thậtgõ yêu cầu dùng swarm của ruflo
- (Tuỳ chọn) Cài plugin hoặc nối MCPdùng nếu bạn không muốn thêm file vào dự án, hoặc dùng Codex
A.Mở terminal đúng thư mục
Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. Hãy mở terminal, đi vào thư mục dự án bạn muốn dùng ruflo. Nếu dự án nằm trên GitHub và bạn chưa tải về, dùng lệnh phổ thông sau (thay đường dẫn bằng repo của bạn):
git clone https://github.com/<tên-bạn>/<dự-án-của-bạn>.git
cd <dự-án-của-bạn>Sau đó có thể kiểm tra Node bằng lệnh phổ thông:
node --versionCon số đầu phải từ 20 trở lên.
B.Chạy lệnh init
Đây là lệnh chính theo 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à settings trong thư mục làm việc. Vì vậy bạn nên chạy trong dự án đã có Git để dễ xem hoặc hoàn tác thay đổi.
Nếu muốn thiết lập theo từng câu hỏi, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code và giao việc
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 rồi mở lại. Sau đó thử một yêu cầu mẫu của chính 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 mình chỉ chép nguyên câu gốc để bạn đối chiếu với README.
D.Cách khác: chỉ cài plugin vào Claude Code
Cách này không thêm file nào vào dự án và cần Claude Code 2.1.287 trở lên. Gõ các lệnh sau bên trong Claude Code (không gõ ở 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: thêm “chợ” plugin của ruflo, cài lõi, cài bảng điều khiển, cài mod, nạp lại plugin rồi mở bảng điều khiển. Nếu dùng Claude Code 2.1.292 trở lên, có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý từ README: bản plugin “lite” chỉ cho lệnh gạch chéo, vài skill và định nghĩa agent. Hook không được cài; MCP server chỉ có khi cài ruflo-core. Muốn đủ vòng làm việc, dùng cách init.
E.Cách khác: Codex hoặc MCP client 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 như sau:
["-y", "ruflo@latest", "mcp", "start"]Tương đương lệnh npx -y ruflo@latest mcp start. Chỗ điền cụ thể tuỳ từng client; README chưa chỉ chi tiết, bạn xem tài liệu của client đó.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một dòng “thành công” cố định, nhưng có vài dấu hiệu bạn có thể kiểm tra:
- Sau
init: trong thư mục dự án xuất hiện.claude/,.claude-flow/vàCLAUDE.md(theo bảng so sánh cách cài). - Trong Claude Code: sau khi mở lại, gõ
/ruflo. README ghi: bắt đầu bằngnpx ruflo init, khởi động lại Claude Code rồi gõ/ruflođể mở bảng điều khiển. - Với cách plugin: gõ
/pluginvà xem plugin có nằm trong dòng “active mods” không. - Không cần Claude Code: thử bảng điều khiển trong terminal bằng lệnh sau. Thêm
--plainđể in một khung duy nhất, hợp cho script.
npx ruflo tuiNếu bảng điều khiển hiện lên và bạn giao được việc mẫu ở trên, coi như cài xong.
V.Dùng vào việc thật
A.Dev nhỏ: rà soát cả repo trước khi giao khách
Bạn là lập trình viên nhận lại một dự án cũ, không biết chỗ nào dễ hỏng. Sau khi init và mở lại Claude Code, bạn gõ đúng yêu cầu mẫu: 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. Kết quả mong đợi là một báo cáo nêu module rủi ro, bộ test mới và bản tóm tắt thay đổi. Hãy đọc lại diff trước khi chấp nhận, vì agent vẫn có thể sai.
ruflo lo phần điều phối, còn bạn vẫn là người quyết định cái gì được vào dự án.
Ông T
B.Người mới: tập giao việc có kiểm soát qua bảng điều khiển
Bạn muốn thử mà chưa dám để AI tự làm gì thì làm. README có bài tập an toàn: mở /ruflo, chọn Settings → Claude control → write + ask. Rồi nhờ 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 bảng điều khiển. Kiểm tra mục Missions có mục tiêu đó và Overview có ghi lại hành động. README nhấn mạnh: 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, các lời gọi sau đó sẽ bị từ chối cho đến khi bạn trả quyền lại.
C.Người dùng Codex: gắn ruflo như một MCP server
Bạn không dùng Claude Code mà dùng Codex hoặc công cụ hỗ trợ MCP. Bạn khai báo command npx với các đối số -y, ruflo@latest, mcp, start như ở phần cài đặt. Công cụ của ruflo sẽ xuất hiện như các tool MCP trong client đó. README chưa mô tả chi tiết từng tool hiển thị ra sao ở mỗi client, nên hãy thử một yêu cầu nhỏ trước.
D.Người muốn thử nhẹ: chỉ cài vài plugin
Bạn chưa muốn thêm file vào dự án. Hãy cài ruflo-core rồi thêm plugin cần thiết theo cùng mẫu lệnh /plugin install <tên>@ruflo. Danh sách plugin trong README gồm, ví dụ, ruflo-swarm (phối hợp nhiều agent), ruflo-rag-memory (truy xuất thông minh) và ruflo-testgen (tìm test còn thiếu và tạo test), ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Kết quả là bạn có thêm lệnh gạch chéo và định nghĩa agent mà không đụng đến cấu trúc dự án.
VI.Lỗi hay gặp và cách xử lý
1. Lệnh npx báo lỗi hoặc phiên bản Node quá cũ. Gói yêu cầu Node từ 20.0.0. Chạy node --version; nếu thấp hơn, cài Node mới rồi mở lại terminal và chạy lại init.
2. Gõ /ruflo mà Claude Code không nhận. Có hai khả năng: chưa khởi động lại sau init, hoặc cài plugin xong chưa nạp. Với plugin, chạy /reload-plugins. Nếu vẫn không thấy, kiểm tra phiên bản Claude Code: cách plugin cần 2.1.287 trở lên (lệnh cài từ terminal cần 2.1.292 trở lên).
3. Cài plugin xong nhưng thiếu công cụ hoặc hook. Đây là điều README nói thẳng: bản plugin chỉ cho lệnh gạch chéo, một số skill và agent. Hook không được cài, MCP chỉ có khi cài ruflo-core. Cần đủ vòng làm việc thì chạy npx ruflo@latest init.
4. Plugin bên ngoài bị nạp hai lần. Với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow, README dặn chỉ cài từ một marketplace. Cài từ cả hai nơi thì mod và lệnh có thể bị nạp đôi. Hãy gỡ một bản.
5. Claude từ chối thao tác trong bảng điều khiển. Rất có thể mức quyền đang là mặc định read + ask. Hành động vượt mức bị từ chối, và những việc liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận. Muốn làm thêm thì nâng mức quyền có chủ ý, đừng bật full + 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ợ Claude Code, Codex và MCP client khác. Bạn có bảng điều khiển để nhìn thấy agent đang làm gì, và có cơ chế phân quyền rõ ràng cho phần “Claude tự điều khiển”. Repo rất hoạt động, cộng đồng lớn.
Giới hạn. Bộ tính năng rất rộng (hàng chục plugin, hàng trăm công cụ), nên với người mới dễ choáng. README tự thừa nhận phần học là “conceptual”, và các video minh hoạ dùng dữ liệu mẫu, không chứng minh việc swarm đã làm xong hay bộ nhớ đã được gọi lại. Cách init thêm khá nhiều file vào dự án. Các mod không bị sandbox. Chi phí token phụ thuộc vào nhà cung cấp mô hình bạn dùng; hãy theo dõi, nhất là khi nhiều agent chạy cùng lúc.
Khi nào chọn cách khác. Nếu việc của bạn nhỏ, một cuộc trò chuyện với Claude Code là đủ, đừng thêm một lớp điều phối. Nếu bạn không muốn công cụ thêm file hoặc chạy mã không cách ly, hãy dùng riêng vài plugin hoặc chỉ nối MCP. Nếu làm việc trong môi trường nhạy cảm, đọc kỹ SECURITY.md của repo trước.
Lời khuyên của mình: cài thử trong một dự án nháp, chạy đúng yêu cầu mẫu ở trên, xem bảng điều khiển, rồi mới quyết định có đưa vào việc thật hay khô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 dùng và chỉnh sửa tự do. Tuy nhiên ruflo bao quanh Claude Code, Codex và các nhà cung cấp mô hình, nên chi phí sử dụng các dịch vụ đó vẫn tính riêng. README có plugin theo dõi token và chi phí, nhưng chưa có thông tin về giá của các dịch vụ này.
Cài ruflo cần những gì?
Theo package.json, bạn cần Node.js từ 20.0.0 trở lên. Cách cài chính là chạy npx ruflo@latest init trong thư mục dự án. Nếu cài bằng plugin thì cần Claude Code 2.1.287 trở lên.
ruflo có cần GPU không?
README phần đã cung cấp không nói rằng bắt buộc phải có GPU. Có một plugin ruflo-ruvector nhắc đến tìm kiếm tăng tốc bằng GPU, nhưng đó là tính năng tuỳ chọn. Yêu cầu phần cứng cụ thể thì chưa có thông tin.
Dùng được ruflo với Codex, hay chỉ dùng được với Claude Code?
Dùng được cả hai. Với Codex hoặc MCP client khác, bạn khai báo command là npx và các đối số -y, ruflo@latest, mcp, start. README cũng có lệnh init riêng cho Grok Build.
Chạy trên Windows được không?
Phần README đã cung cấp không nêu rõ danh sách hệ điều hành được hỗ trợ. Các lệnh chính chạy qua Node và npx. Nếu bạn dùng Windows, hãy thử trong một dự án nháp và xem thư mục docs/ của repo để biết thêm.
ruflo có an toàn không, có sửa file của tôi không?
Lệnh init thêm các file như .claude/, .claude-flow/ và CLAUDE.md vào dự án, nên hãy chạy trong dự án có Git. Các mod 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. Quyền của Claude trong bảng điều khiển mặc định là read + ask, và các hành động về mạng, chi tiêu, phá huỷ luôn cần xác nhận.
ruflo khác gì dùng Claude Code bình thường?
Claude Code là công cụ để mô hình viết và sửa mã. ruflo là lớp harness thêm vào: nhiều agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook, bảng điều khiển và các chốt kiểm soát. Sau khi cài, bạn vẫn dùng Claude Code như thường, còn ruflo tự định tuyến và phối hợp ở phía sau.


