Ruflo: điều phối nhiều agent AI cho Claude Code — 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 để chia việc cho nhiều agent, nhớ qua các phiên và kiểm soát quyền hạn. Bạn cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài không khó, nhưng repo rất rộng nên người mới nên bắt đầu từ một việc nhỏ.
Ruflo là một "agent harness" mã nguồn mở viết bằng TypeScript: một lớp công cụ bao quanh Claude Code và Codex để các agent AI làm việc có tổ chức hơn. Nói đơ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ề: có công cụ, có trí nhớ, có vòng lặp kiểm tra và có giới hạn quyền hạn. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.582 sao và 9.607 fork, giấy phép MIT.
Bạn nên xem Ruflo nếu đang dùng Claude Code hoặc Codex cho việc lập trình và thấy một agent đơn lẻ làm chưa đủ. Ví dụ: bạn muốn một nhóm agent cùng rà soát dự án, viết test, rồi tóm tắt lại. Nó cũng hợp với người mới, vì tác giả nói rõ sau khi chạy init bạn cứ dùng Claude Code như bình thường, hệ thống hook sẽ tự định tuyến tác vụ ở phía sau.
Điểm đáng giá nhất là cài rất gọn: một lệnh npx là có agent, hook, bộ nhớ và MCP server trong dự án. Ngoài ra còn có một bảng điều khiển (console) ngay cạnh Claude Code để theo dõi agent, token và chi phí. Bài này đi từ cài đặt đến vài tình huống dùng thật, kèm những chỗ người mới hay vấp.
ruvnet/ruflo
Ruflo là bộ khung chạy quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, hook và MCP server chỉ bằng một lệnh npx.
I.Ruflo làm được gì
Repo rất lớn, nên mình chỉ nói những phần bạn dễ cảm nhận nhất.
A.Chia việc cho nhiều agent (swarm)
Thay vì một agent làm tất cả, Ruflo cho các agent tự tổ chức thành nhóm. README nói đường cài đầy đủ mang theo 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: bạn giao một việc lớn như "rà soát cả repo" và để nhóm agent chia nhau làm, thay vì tự chia nhỏ yêu cầu.
B.Bộ nhớ và tự học
Theo README, agent nhớ được kinh nghiệm qua nhiều phiên và dùng lại để định tuyến tác vụ về sau. Nhờ vậy bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code. README cũng nói rõ phần "tự học" là mô hình khái niệm. Việc tìm kiếm vector cục bộ có thể chạy không cần LLM, nhưng embeddings và các module học được cấu hình vẫn là bắt buộc.
C.Bảng điều khiển /ruflo
Đây là "buồng lái" nằm cạnh Claude Code. Bạn theo dõi workflow, agent, model, token và chi phí, mở 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. Với người làm kinh doanh, phần theo dõi chi phí là thứ đáng chú ý nhất, vì bạn thấy ngay agent đang tiêu bao nhiêu token.
D.Cho Claude tự điều khiển, nhưng bạn đặt giới hạn
Trong Settings có mục Claude control. Bạn chọn mức quyền read, write, manage hoặc full, và chọn duyệt kiểu ask hoặc auto. Mặc định hiện là read + ask, tức Claude chỉ đọc và phải hỏi bạn. Các hành động mạng, tốn tiền hoặc phá hủy vẫn phải xác nhận ngay cả khi để auto. Có nút "Take back control" để dừng ngay.
E.Hệ plugin lớn
Repo có hàng chục plugin theo nhóm: điều phối (swarm, workflows, autopilot), bộ nhớ (agentdb, rag-memory), kiểm thử (testgen, browser), bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker)… Bạn cài từng cái khi cần, không phải dùng hết.
F.Chạy với nhiều công cụ khác
Ngoài Claude Code, README nói Codex và các MCP client khác dùng được. Có cả tùy chọn --grok cho Grok Build và một giao diện terminal chạy riêng.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu những yêu cầu sau:
- Node.js từ 20.0.0 trở lên. Đây là yêu cầu trong
package.jsoncủa gói. - Claude Code, nếu bạn muốn dùng đường cài đặt chính. README nói Claude Code sẽ nhận các thành phần Ruflo ở lần khởi động kế tiếp.
- Claude Code phiên bản 2.1.287 trở lên nếu bạn chọn đường cài bằng plugin. Lệnh
claude plugin installtừ terminal cần 2.1.292 trở lên. - Một thư mục dự án để chạy
init.
Về hệ điều hành, tài khoản và API key, README đoạn mình có chưa nêu yêu cầu cụ thể. Bạn cần tài khoản Claude Code (hoặc Codex) theo cách bạn vẫn dùng bình thường. Phần phần cứng và GPU chưa có thông tin trong tư liệu, nên bạn hãy xem thêm thư mục docs/ của repo.
Mod trong Ruflo chạy với quyền tài khoản của bạn và không bị sandbox. Hãy đọc mã nguồn trước khi cài. Với tính năng Claude control, cứ để mặc định read + ask cho đến khi bạn hiểu rõ nó làm gì.
III.Cài đặt từng bước
- Kiểm tra NodeChạy node -v, cần 20 trở lên
- Mở terminal trong dự ánVào đúng thư mục bạn muốn dùng Ruflo
- Chạy initnpx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP
- Mở lại Claude CodeKhởi động Claude Code trong cùng thư mục
- Mở bảng điều khiểnGõ /ruflo trong Claude Code
A.Kiểm tra phiên bản Node
Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) và chạy lệnh dưới. Kết quả phải là v20 trở lên.
node -vNếu thấy số nhỏ hơn 20 hoặc báo không tìm thấy lệnh, bạn cần cài hoặc nâng cấp Node trước.
B.Vào thư mục dự án
Chỗ này 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 mở terminal đúng thư mục dự án. Ví dụ với một repo có sẵn:
git clone https://github.com/<tên-repo-của-bạn>.git
cd <tên-thư-mục>Thay phần trong dấu <> bằng dự án thật của bạn. Nếu đã có thư mục dự án rồi thì chỉ cần cd vào đó.
C.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initnpx tải và chạy gói tạm thời, không cần cài toàn cục. Theo README, init thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Bảng so sánh trong README ghi đường này tạo ra các mục như .claude/, .claude-flow/ và CLAUDE.md trong thư mục làm việc, nên bạn sẽ thấy file mới xuất hiện.
Nếu muốn thiết lập theo kiểu hỏi đáp, README có lệnh:
npx ruflo@latest init wizardD.Mở lại Claude Code
Đóng Claude Code nếu đang mở, rồi mở lại 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 quên bước này, bạn sẽ không thấy gì thay đổi.
E.Cách khác: chỉ cài plugin trong Claude Code
Nếu bạn không muốn thêm file vào dự án, README có đường plugin (cần Claude Code 2.1.287 trở lên). Gõ lần lượt các lệnh này 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
/rufloĐường này đưa vào công cụ lõi, bảng điều khiển và mod, với số file thêm vào dự án là không. Bù lại, README cho biết nó gọn hơn: chỉ có lệnh slash, vài skill và định nghĩa agent, không có hook, và MCP server chỉ có khi cài ruflo-core. Muốn dùng đầy đủ như tài liệu mô tả thì chọn npx ruflo@latest init.
F.Dùng với Codex hoặc MCP client khác
Cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Cách điền cụ thể tùy từng công cụ, bạn xem tài liệu của client bạn dùng.
["-y", "ruflo@latest", "mcp", "start"]G.Chạy riêng bảng điều khiển trong terminal
Không cần Claude Code cũng chạy được giao diện console:
npx ruflo tuiThêm --plain nếu bạn muốn in ra một khung hình để dùng trong script.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra đơn giản nhất theo README:
- Sau khi chạy
npx ruflo@latest init, mở lại Claude Code trong cùng thư mục. - Gõ
/ruflo. Nếu bảng điều khiển hiện ra thì thành phần console đã hoạt động. - Nếu cài bằng plugin, gõ
/pluginđể xem các mod có nằm trong dòng "active mods" không. - Thử một việc nhỏ. README gợi ý nhờ Claude tạo một "mission" rồi kiểm tra mục Missions và trang Overview có ghi lại hành động đó.
Lưu ý một chi tiết README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được làm xong. Mission chỉ ghi lại mục tiêu.
Nếu /ruflo không có phản hồi, hãy xem phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
A.Rà soát một dự án có sẵn
Bối cảnh: bạn là lập trình viên mới nhận một dự án cũ, chưa biết phần nào dễ hỏng. Sau khi chạy init và mở lại Claude Code, bạn dùng đúng câu README gợi ý:
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: nhóm agent tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn nên đọc lại phần test và thay đổi trước khi giữ chúng, vì agent vẫn có thể sai.
Agent = Model + Harness. Mô hình viết, còn harness mới là thứ giúp nó thật sự làm việc được.
Ông T
B.Theo dõi chi phí khi giao việc dài
Bối cảnh: bạn là chủ một shop nhỏ, tự thuê dev freelance và dùng Claude Code để sửa website. Bạn lo agent chạy lâu sẽ tốn token mà không biết. Mở /ruflo để xem token và chi phí ngay cạnh phiên làm việc. README cũng liệt kê plugin ruflo-cost-tracker với mô tả theo dõi token, đặt ngân sách và cảnh báo chi phí. Plugin này cài theo cùng kiểu lệnh /plugin install như các plugin khác.
/plugin install ruflo-cost-tracker@rufloKết quả: bạn thấy được mức tiêu tốn thay vì đoán, và có cơ sở để quyết định có nên cho agent chạy tiếp hay không.
C.Để Claude thao tác bảng điều khiển, bạn duyệt từng bước
Bối cảnh: bạn là nhân viên văn phòng quản lý một nhóm việc, muốn thử cho Claude tự tạo mục tiêu nhưng chưa dám cho toàn quyền. Làm theo ví dụ trong README:
- Mở
/ruflo, vào Settings → Claude control và chọn write + ask. - Nhờ 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 mới đang chờ trong console.
- Kiểm tra Missions có mục tiêu đó và Overview có ghi lại hành động.
Kết quả: Claude tạo mission sau khi bạn đồng ý. Muốn dừng lúc nào cũng được bằng nút Take back control, và những lệnh sau đó sẽ bị từ chối cho tới khi bạn trả quyền lại.
D.Cắm Ruflo vào công cụ khác qua MCP
Bối cảnh: bạn dùng Codex hoặc một ứng dụng hỗ trợ MCP thay vì Claude Code. Bạn không cần thiết lập dự án, chỉ cần khai báo máy chủ MCP với command npx và các đối số ở phần cài đặt phía trên. Muốn thiết lập theo dự án thì chạy npx ruflo@latest init wizard.
Kết quả: công cụ của bạn gọi được các công cụ MCP của Ruflo. Số lượng công cụ README nêu là 406 MCP tool, nhưng tác giả nói bạn không cần học hết, cứ dùng bình thường là được.
VI.Lỗi hay gặp và cách xử lý
A.Báo thiếu Node hoặc Node quá cũ
npx có thể lỗi hoặc cài không hoàn tất nếu Node dưới 20. Chạy node -v để xem, rồi nâng Node lên 20 trở lên trước khi thử lại.
B.Mở Claude Code nhưng không thấy gì mới
Thường là bạn chưa khởi động lại Claude Code, hoặc mở nó ở thư mục khác với nơi chạy init. Đóng Claude Code, cd vào đúng thư mục dự án rồi mở lại. Nếu dùng đường plugin, chạy /reload-plugins rồi /ruflo.
C.Lệnh /plugin hoặc claude plugin install không nhận
Đường plugin cần Claude Code từ 2.1.287 trở lên, còn lệnh cài từ terminal cần từ 2.1.292 trở lên. Hãy cập nhật Claude Code lên bản mới hơn. Nếu vẫn không được, quay lại cách npx ruflo@latest init.
D.Thấy nhiều file lạ trong dự án
Đây là bình thường với đường init: README ghi sẽ có .claude/, .claude-flow/ và CLAUDE.md. Nếu dự án dùng Git, hãy xem git status trước khi commit để quyết định file nào giữ lại. Muốn không thêm file nào, dùng đường plugin. README cũng có cờ --dry-run để xem trước, nhưng chỉ ghi cho lệnh init --grok. Với lệnh init thường, README đoạn mình có chưa nói cờ này có dùng được hay không.
E.Cài cùng một plugin từ hai nơi
Với các plugin ngoài như agentic-qe-fleet, README cảnh báo chỉ nên cài từ một marketplace. Nếu bật từ cả hai nơi, mod và lệnh sẽ bị nạp hai lần. Hãy gỡ một bản đi.
VII.Có nên dùng không
Điểm mạnh:
- Cài nhanh bằng một lệnh, mở Claude Code là dùng.
- Có bảng điều khiển để thấy agent, token và chi phí.
- Quyền hạn rõ ràng: mặc định chỉ đọc và hỏi, hành động tốn tiền hay phá hủy luôn cần bạn xác nhận.
- Giấy phép MIT, repo vẫn được cập nhật trong 3 tháng gần đây.
- Cài từng plugin riêng được, không bắt buộc dùng cả hệ.
Giới hạn:
- Repo rất rộng (hàng chục plugin, hàng trăm công cụ MCP). Người mới dễ choáng, nên bắt đầu từ một việc nhỏ.
- Mod không bị sandbox và chạy với quyền tài khoản của bạn, nên phải đọc mã trước khi cài.
- Đường
initthêm file vào dự án. Đường plugin gọn hơn nhưng không có hook. - Tính năng tự học chỉ là mô hình khái niệm theo chính README, đừng kỳ vọng nó "tự thông minh" ngay.
- Các đoạn demo trong README dùng dữ liệu mẫu hoặc phát lại khung hình, chúng không phải bằng chứng cho việc swarm hoàn thành công việc thật.
Khi nào nên chọn cách khác: nếu bạn chỉ nhờ AI sửa vài file nhỏ, Claude Code thuần là đủ. Ruflo đáng thử khi bạn có việc dài, nhiều bước, cần nhớ bối cảnh và muốn theo dõi chi phí. Nếu bạn không rành kỹ thuật, hãy thử trên một dự án nháp trước và để Claude control ở mức mặc định.
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 và sửa tự do. Tuy vậy, tư liệu không nói gì về chi phí của các mô hình AI phía sau. Bạn vẫn trả theo cách bạn dùng Claude Code, Codex hay nhà cung cấp khác.
Cài Ruflo cần những gì?
Cần Node.js từ 20.0.0 trở lên. Nếu dùng đường plugin thì cần Claude Code 2.1.287 trở lên. Lệnh cài chính là `npx ruflo@latest init`, chạy trong thư mục dự án.
Ruflo khác gì Claude Code thuần?
Theo README, Ruflo là lớp harness bao quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ, hook và bảng điều khiển. Claude Code vẫn là nơi bạn làm việc. Ruflo bổ sung phần điều phối và theo dõi.
Có cần GPU không?
Tư liệu mình có chưa nói yêu cầu về GPU hay phần cứng. Một plugin của Ruflo có nhắc tìm kiếm tăng tốc bằng GPU, nhưng đó là tùy chọn riêng. Bạn nên xem thư mục docs/ của repo nếu cần chắc chắn.
Chạy được trên Windows không?
README đoạn mình có không nêu hệ điều hành cụ thể. Các lệnh đều chạy qua `npx` nên cần Node 20 trở lên. Về độ tương thích Windows, hiện chưa có thông tin chính thức trong tư liệu.
Cho Claude điều khiển Ruflo có an toàn không?
README cho biết mặc định là read + ask, tức chỉ đọc và phải hỏi bạn. Hành động qua mạng, tốn tiền hoặc phá hủy vẫn cần xác nhận ngay cả ở chế độ auto. Bạn có thể bấm Take back control để dừng ngay. Mod thì không bị sandbox nên phải đọc mã trước khi cài.
Dùng được với Codex hay công cụ khác ngoài Claude Code không?
Có. README nói Codex và các MCP client khác trỏ tới `npx -y ruflo@latest mcp start` là dùng được. Ngoài ra có tùy chọn `npx ruflo init --grok` cho Grok Build.


