Ruflo: điều phối nhóm 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": lớp công cụ bao quanh Claude Code hoặc Codex để chia việc cho nhiều agent, có bộ nhớ qua các phiên và có hook tự chạy. Bạn dùng nó để giao những việc lớn như rà soát cả repo, viết test, tóm tắt thay đổi. Cài đặt chỉ cần Node 20 trở lên và một lệnh `npx ruflo@latest init`, nên khá dễ với người đã dùng Claude Code.
Ruflo là một bộ công cụ "bọc" quanh Claude Code và Codex, gọi là agent harness. 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 đủ đồ nghề quanh người đó. Nó thêm các agent chuyên biệt, bộ nhớ nhớ được giữa các lần làm việc, các hook tự động và một MCP server để Claude Code dùng. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.600 sao và 9.600 fork trên GitHub, giấy phép MIT.
Bạn nên quan tâm nếu đang dùng Claude Code hoặc Codex và thấy một cuộc trò chuyện đơn lẻ không đủ cho việc lớn. Ví dụ: rà soát cả một dự án, tìm chỗ rủi ro nhất rồi viết test cho chỗ đó. Ruflo cho phép chia việc ấy cho nhiều agent làm phối hợp (swarm), thay vì một agent ôm hết. Lập trình viên mới, người làm kinh doanh có dự án phần mềm nhỏ, hay nhân viên văn phòng đang tập dùng AI viết code đều có thể thử.
Điểm đáng giá nhất là cách vào cuộc rất nhẹ: một lệnh npx ruflo@latest init trong thư mục dự án, rồi bạn cứ dùng Claude Code như bình thường. README nói rõ bạn không cần học hết hàng trăm công cụ MCP hay hàng chục lệnh CLI. Sau init, hệ thống hook sẽ tự định tuyến tác vụ và phối hợp agent ở phía sau.
ruvnet/ruflo
Ruflo là lớp điều phối bao quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server chỉ với một lệnh npx.
I.Ruflo làm được gì
Dưới đây là các nhóm tính năng chính, tóm theo ý nghĩa thực tế chứ không chép lại danh sách dài trong README.
A.Đội agent chuyên biệt làm việc cùng nhau
Ruflo đi kèm hàng chục agent định nghĩa sẵn (README ghi con số khác nhau ở các chỗ, từ 98 đến hơn 100). Chúng có thể được gom thành swarm, tức một nhóm tự chia việc. Lợi ích: một việc lớn như "rà soát và viết test" được tách thành nhiều phần nhỏ chạy song song, thay vì bạn phải tự chia và dán từng đoạn vào chat.
B.Bộ nhớ qua nhiều phiên
Phần bộ nhớ dùng cơ sở dữ liệu vector, nên agent có thể tìm lại kinh nghiệm cũ khi gặp việc tương tự. README ghi chú đây là mô hình học "theo 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. Nói cách khác, đừng kỳ vọng nó "tự thông minh lên" mà không cài đặt gì.
C.Hook tự định tuyến và học
Hook là các đoạn tự chạy khi Claude Code làm việc. Ruflo dùng chúng để chọn agent phù hợp cho tác vụ và ghi lại mẫu làm việc thành công. Bạn không phải gõ lệnh riêng cho từng việc.
D.Bảng điều khiển ngay trong Claude Code
Plugin ruflo-console là một "buồng lái": theo dõi workflow, agent, mô hình, token và chi phí bên cạnh Claude Code. Bạn mở nó bằng lệnh /ruflo. Bạn có thể xem log của từng lần chạy, tìm kiếm, phân loại lỗi, phát lại và so sánh.
E.Cho Claude điều khiển, nhưng bạn đặt giới hạn
Trong Settings → Claude control, 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. Theo README, các hành động vượt quyền sẽ bị từ chối, còn hành động liên quan mạng, chi tiền hoặc phá huỷ vẫn phải xác nhận kể cả ở chế độ auto. Bạn có thể bấm Take back control để dừng ngay.
F.Hệ sinh thái plugin
README liệt kê 48 plugin, chia theo nhóm: điều phối, bộ nhớ, học tập, kiểm thử, bảo mật, DevOps, mở rộng… Một vài ví dụ dễ hiểu:
ruflo-swarm: phối hợp nhiều agent như một đội.ruflo-testgen: tìm chỗ thiếu test và sinh test.ruflo-cost-tracker: theo dõi token, đặt ngân sách, cảnh báo chi phí.ruflo-security-audit: quét lỗ hổng và CVE.ruflo-aidefence: chặn prompt injection, phát hiện thông tin cá nhân.
G.Dùng được với nhiều ứng dụng khách
Ngoài Claude Code, README nói Codex và các MCP client khác cũng dùng được. Ngoài ra có lệnh npx ruflo init --grok cho Grok Build, và một giao diện terminal chạy độc lập.
II.Cần chuẩn bị gì
Theo tư liệu của repo, bạn cần:
- Node.js từ phiên bản 20.0.0 trở lên.
package.jsonyêu cầu>=20.0.0. Lệnhnpxđi kèm Node. - Claude Code nếu muốn dùng theo cách chính. Nếu chọn cài qua plugin thì cần Claude Code 2.1.287 trở lên. Lệnh cài từ terminal (
claude plugin install ...) cần 2.1.292 trở lên. - Một thư mục dự án để chạy
init. Lệnh này thêm file vào chính thư mục đó. - Tài khoản và API key: README phần được cung cấp không nói rõ bạn cần key riêng nào. Bạn vẫn cần quyền dùng Claude Code (hoặc Codex) như bình thường. Chi tiết khác xem trong README và các hướng dẫn trong thư mục
docs/của repo. - Hệ điều hành, GPU: phần README tôi có không nêu yêu cầu cụ thể. Repo có cả TypeScript lẫn Rust (
Cargo.toml), nhưng cách chạy bằngnpxthì chỉ cần Node.
Mods và plugin chạy với đúng quyền tài khoản của bạn và không nằm trong sandbox, theo chính README. Hãy đọc mã nguồn trước khi cài. Ruflo cũng có thể làm tăng lượng token mà Claude dùng, nên hãy theo dõi chi phí ở lần chạy đầu.
III.Cài đặt từng bước
Cách nhanh nhất là dùng lệnh init. Dưới đây là các bước tóm tắt.
- Kiểm tra NodeXác nhận máy có Node 20 trở lên
- Mở terminal trong dự ánVào đúng thư mục dự án bạn muốn dùng
- Chạy initChạy npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao việc thửDán một câu lệnh mẫu để Ruflo chạy swarm
A.Kiểm tra phiên bản Node
Mở terminal (PowerShell trên Windows, Terminal trên macOS) và gõ lệnh dưới đây. Nếu số hiện ra nhỏ hơn 20, hãy nâng cấp Node trước.
node --versionB.Mở terminal đúng thư mục dự án
Đây là chỗ người mới hay vấp: init thêm file vào thư mục hiện tại, nên bạn phải đứng đúng trong thư mục dự án. Thay ten-du-an bằng tên thư mục thật của bạn.
cd ten-du-anC.Chạy lệnh init
Đây là lệnh chính của README. Nó thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh trong README, cách này tạo thêm các thư mục như .claude/, .claude-flow/ và file CLAUDE.md trong dự án của bạn.
npx ruflo@latest initNếu muốn thiết lập có hướng dẫn từng câu hỏi, README có thêm lệnh:
npx ruflo@latest init wizardD.Mở lại Claude Code
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu Claude Code đang mở sẵn, hãy thoát và mở lại.
E.Giao một việc thật
Dán câu mẫu sau vào Claude Code:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.F.Cách khác: chỉ cài plugin trong 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 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
/rufloTừ terminal, với Claude Code 2.1.292 trở lên, README ghi thêm một lệnh:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý: cách plugin chỉ cho "bản nhẹ": lệnh gạch chéo và vài skill. Cách init mới là vòng Ruflo đầy đủ, theo bảng so sánh của README.
G.Cách khác: dùng với Codex hoặc MCP client khác
Cấu hình client của bạn với command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Nghĩa là client sẽ tự chạy lệnh npx -y ruflo@latest mcp start để khởi động MCP server. Mỗi client điền cấu hình ở một chỗ khác nhau, README phần tôi có không chỉ chỗ cụ thể, nên bạn xem tài liệu của client đó.
H.Cách khác: giao diện terminal riêng
Bảng điều khiển cũng chạy độ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
Sau khi chạy init và mở lại Claude Code, bạn kiểm tra theo thứ tự này:
- Lệnh
initkhông báo lỗi và trong thư mục dự án xuất hiện các thư mục/file mà README nói tới, như.claude/,.claude-flow/vàCLAUDE.md. - Gõ
/ruflotrong Claude Code. README hướng dẫn: chạynpx ruflo init, khởi động lại Claude Code, rồi gõ/ruflo. Nếu bảng điều khiển hiện ra là cài xong. - Với cách plugin, gõ
/pluginvà xem plugin có nằm trong dòng "active mods" không. - Thử một việc nhỏ có thể kiểm chứng. Ví dụ trong README: đặt quyền ở Settings → Claude control là write + ask, rồi yêu cầu:
Create a mission to add a dark mode toggle. Show me the mission and its status.Claude sẽ mở trang Missions và đặt mục tiêu. Bạn xác nhận hành động tạo, rồi kiểm tra mục tiêu có trong Missions và Overview có ghi lại hành động không. README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong.
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 dự án và mô hình bạn dùng.
A.Rà soát dự án thừa kế để tìm chỗ rủi ro
Bối cảnh: bạn là lập trình viên mới vừa nhận một dự án của người khác, ít test, và không biết nên đụng vào đâu trước.
Cách làm: chạy npx ruflo@latest init trong thư mục dự án, mở lại Claude Code rồi dán 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ả: nhóm agent chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn đọc phần tóm tắt trước, rồi mới xem từng file test được thêm.
Đừng học hết 400 công cụ. Chạy init, mở Claude Code và giao một việc thật.
Ông T
B.Giao việc cho Claude trong bảng điều khiển nhưng vẫn giữ quyền
Bối cảnh: bạn quản lý một dự án nhỏ và muốn AI ghi lại các hạng mục việc, nhưng chưa muốn nó tự ý chạy lệnh lớn.
Cách làm: cài ruflo-console (qua plugin hoặc init), gõ /ruflo, vào Settings → Claude control và chọn write + ask. Sau đó yêu cầu tạo một mission như ví dụ dark mode ở phần trên.
Kết quả: mỗi hành động ghi đều cần bạn bấm xác nhận. Nếu thấy không ổn, bấm Take back control và các lời gọi sau đó sẽ bị từ chối cho đến khi bạn khôi phục quyền.
C.Dùng Ruflo với Codex hoặc công cụ MCP khác
Bối cảnh: nhóm bạn không chỉ dùng Claude Code mà còn dùng Codex hoặc một ứng dụng hỗ trợ MCP.
Cách làm: không cần chạy init. Trong cấu hình MCP của ứng dụng, đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Muốn thiết lập theo dự án thì chạy npx ruflo@latest init wizard.
Kết quả: ứng dụng khách gọi được các công cụ của Ruflo qua MCP, ví dụ công cụ bộ nhớ và điều phối agent. Tên công cụ cụ thể xem trong tài liệu của repo.
D.Chỉ thử một plugin, không đụng vào dự án
Bối cảnh: bạn tò mò về Ruflo nhưng sợ nó thêm file lung tung vào thư mục làm việc.
Cách làm: dùng đường plugin trong Claude Code. Thêm marketplace, rồi cài từng plugin bạn cần, ví dụ ruflo-core và ruflo-swarm:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@rufloKết quả: theo README, cách này không thêm file nào vào workspace và không cài hook. Bạn chỉ có các lệnh gạch chéo và định nghĩa agent của plugin. Khi muốn vòng đầy đủ thì chuyển sang npx ruflo@latest init.
VI.Lỗi hay gặp và cách xử lý
README phần tôi có không có mục khắc phục sự cố riêng, nên các mục dưới đây là những chỗ rất dễ vấp dựa trên yêu cầu mà tư liệu nêu. Cần thêm thì xem thư mục docs/ trong repo.
A.Lệnh npx báo lỗi hoặc không chạy
Thường do Node cũ. package.json yêu cầu Node 20 trở lên. Chạy node --version, nếu thấp hơn thì cài bản Node mới rồi chạy lại npx ruflo@latest init.
B.Không thấy Ruflo trong Claude Code sau khi init
Claude Code chỉ nhận cấu hình mới ở lần khởi động tiếp theo. Hãy thoát hẳn rồi mở lại, và chắc chắn bạn mở nó trong cùng thư mục đã chạy init. Sau đó thử gõ /ruflo.
C.Lệnh /plugin không nhận hoặc cài plugin thất bại
Cách plugin cần Claude Code 2.1.287 trở lên, và lệnh claude plugin install từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code. Sau khi cài, gõ /reload-plugins rồi /plugin để xem plugin đã hiện chưa.
D.Cài một plugin từ hai nơi bị nạp đôi
README cảnh báo với các plugin bên ngoài như agentdb, agentic-flow và agentic-qe-fleet: chỉ cài từ một marketplace. Nếu bật từ cả hai, mod và lệnh sẽ bị nạp hai lần. Nếu đã lỡ, hãy tắt một bản trong /plugin.
E.Claude từ chối hành động trong bảng điều khiển
Đây thường là hành vi đúng, không phải lỗi: mức quyền mặc định là read + ask, và các hành động vượt quyền bị từ chối. Nếu bạn thật sự muốn Claude tạo hoặc sửa, hãy nâng lên write trong Settings → Claude control. Hành động liên quan mạng, chi tiền hoặc phá huỷ vẫn luôn cần bạn xác nhận.
VII.Có nên dùng không
Điểm mạnh. Cài rất gọn nếu bạn đã có Node và Claude Code: một lệnh, mở lại, dùng. Giấy phép MIT. Repo còn được cập nhật trong vài tháng gần đây và có hệ sinh thái plugin rộng, kèm cơ chế quyền rõ ràng cho bảng điều khiển (read, write, manage, full; ask hoặc auto). README cũng thẳng thắn ở nhiều chỗ: ví dụ nói bản demo dùng dữ liệu mẫu và không chứng minh swarm đã hoàn thành việc thật.
Giới hạn. Ruflo khá lớn: hàng chục plugin, hàng trăm công cụ MCP và rất nhiều khái niệm (swarm, federation, vector RAG…). Người mới dễ bị ngợp, nên hãy bắt đầu bằng một việc nhỏ. init thêm nhiều file vào dự án, nên hãy thử trên một dự án có Git để dễ xem và hoàn tác. Mod chạy với quyền của tài khoản bạn và không có sandbox. Việc học tự động chỉ hoạt động khi embedding và module học đã được cấu hình. Ngoài ra tôi chưa thấy tư liệu nào nói rõ chi phí token khi chạy nhiều agent, nên bạn cần tự theo dõi.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời một việc đơn lẻ, cứ dùng Claude Code thuần là đủ, không cần thêm lớp điều phối. Nếu bạn cần một công cụ rất nhỏ, chỉ làm một việc, hãy cài đúng một plugin thay vì cả bộ. Còn nếu bạn muốn nhiều agent phối hợp, có bộ nhớ lâu dài và bảng điều khiển để theo dõi, Ruflo là lựa chọn đáng thử.
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à chỉnh sửa mã nguồn. Tuy nhiên Ruflo chạy trên Claude Code hoặc Codex, và các dịch vụ AI đó có chi phí riêng theo gói của bạn. Tư liệu tôi có chưa nêu chi tiết về chi phí token khi chạy nhiều agent.
Ruflo khác gì Claude Flow?
Đây là cùng một dự án. README cho biết Claude Flow đã được đổi tên thành Ruflo. Tên gói npm của repo vẫn ghi là claude-flow, còn lệnh trong hướng dẫn dùng `npx ruflo@latest`.
Cài Ruflo cần những gì?
Bạn cần Node.js từ phiên bản 20 trở lên. Nếu cài qua plugin thì cần Claude Code 2.1.287 trở lên. Phần README tôi có không nêu yêu cầu GPU hay hệ điều hành cụ thể.
Ruflo có chạy được trên Windows không?
Tư liệu chưa có phần nào nói rõ về hệ điều hành được hỗ trợ. Lệnh cài chỉ là `npx ruflo@latest init` nên về nguyên tắc chạy được nơi có Node 20 trở lên, nhưng bạn nên tự thử và xem tài liệu trong thư mục docs của repo.
Ruflo có làm hỏng dự án của tôi không?
Lệnh `init` thêm file vào dự án, như thư mục .claude, .claude-flow và CLAUDE.md. Vì vậy bạn nên thử trên dự án có Git để dễ xem thay đổi. Nếu muốn không thêm file nào, README có đường cài chỉ bằng plugin trong Claude Code.
Claude có thể tự làm mọi thứ 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ế độ ask hoặc auto, và mặc định hiện là read + ask. Theo README, hành động liên quan mạng, chi tiền hoặc phá huỷ vẫn cần xác nhận kể cả ở chế độ auto, và bạn có thể bấm Take back control để dừng.
Dùng được với Codex hoặc công cụ ngoài Claude Code không?
Có. README nói Codex và các MCP client khác dùng được bằng cách trỏ tới lệnh `npx -y ruflo@latest mcp start`. Có thêm lệnh `npx ruflo init --grok` cho Grok Build.


