ruflo: điều phối nhiều 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ụ bọc quanh Claude Code và Codex để thêm đội agent, bộ nhớ qua nhiều phiên, hook và MCP server. Cài chỉ bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Bạn cũng có thể chọn đường nhẹ hơn là cài plugin trong Claude Code, không thêm file nào vào dự án.
ruflo là một "agent harness", tức bộ khung đặt quanh Claude Code hoặc Codex để AI làm việc có tổ chức hơn. Model lo việc viết, còn ruflo lo phần còn lại: công cụ, bộ nhớ, vòng lặp, kiểm soát quyền. Repo này trước kia tên Claude Flow, hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, giấy phép MIT.
Vấn đề nó giải quyết khá quen thuộc. Bạn dùng Claude Code, mỗi phiên làm việc lại bắt đầu từ đầu, một agent làm một việc, không nhớ lần trước đã học được gì. ruflo thêm vào hơn 100 agent chuyên biệt, cơ chế "swarm" (nhiều agent phối hợp như một đội), bộ nhớ lưu qua các phiên, và một MCP server để các công cụ khác cắm vào.
Ai nên đọc bài này? Lập trình viên mới đã quen với Claude Code và muốn thử làm việc với nhiều agent. Cũng hợp với người làm kỹ thuật trong doanh nghiệp, muốn thấy AI chạy có kiểm soát (chi phí, quyền, nhật ký). Điểm đáng giá nhất: bạn không phải 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, các hook sẽ tự định tuyến tác vụ và phối hợp agent phía sau.
ruvnet/ruflo
ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent, swarm, bộ nhớ dài hạn và MCP server chỉ với một lệnh npx.
I.ruflo làm được gì
A.Đội agent và swarm
Thay vì một agent làm tất cả, ruflo cho nhiều agent tự sắp xếp thành một đội để chia việc. README nhắc đến 98 agent khi cài theo kiểu CLI. Lợi ích thực tế: một nhiệm vụ lớn như rà soát cả repo có thể chia ra, mỗi agent lo một phần rồi báo kết quả gộp lại.
B.Bộ nhớ qua nhiều phiên
ruflo có bộ nhớ để agent nhớ kinh nghiệm từ các lần làm trước và dùng lại cho lần sau. Các plugin như ruflo-agentdb (cơ sở dữ liệu vector cho bộ nhớ agent), ruflo-rag-memory (tìm kiếm thông minh) và ruflo-rvf (lưu và khôi phục bộ nhớ giữa các phiên) phục vụ phần này. README có lưu ý trung thực: phần học này là mô hình khái niệm, việc truy xuất vector cục bộ chạy được không cần LLM nhưng vẫn cần embedding và các module học đã cấu hình.
C.Bảng điều khiển (console) ngay cạnh Claude Code
Plugin ruflo-console cho bạn một "buồng lái": theo dõi workflow, agent, model, token và chi phí. Bạn mở log của từng agent, tìm kiếm, xem lại các lần chạy thất bại. Console cũng chạy riêng được trong terminal thường bằng npx ruflo tui.
D.Cho Claude điều khiển, bạn đặt giới hạn
Trong Settings có mục Claude control. Bạn chọn mức read, write, manage hoặc full, và chọn duyệt ask (hỏi từng lần) hoặc auto. Mặc định hiện là read + ask. Hành động vượt quyền sẽ bị từ chối, còn các hành động liên quan mạng, chi tiền hay phá huỷ vẫn phải xác nhận kể cả ở chế độ auto.
E.Hệ plugin lớn
README liệt kê 48 plugin, chia theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ, học tăng cường, chất lượng code (testgen, browser, docs), bảo mật (security-audit, aidefence), DevOps (cost-tracker, observability)… Bạn cài lẻ plugin nào cần, không bắt buộc lấy hết.
F.Tích hợp nhiều công cụ
Ngoài Claude Code, ruflo chạy được với Codex và các MCP client khác. README còn có tuỳ chọn --grok cho Grok Build.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js 20 trở lên.
package.jsonghi yêu cầu>=20.0.0. Lệnhnpxđi kèm Node. - Claude Code nếu bạn dùng đường chính. Riêng đường cài plugin thì cần Claude Code 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.
- Hoặc Codex / một MCP client khác nếu bạn không dùng 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 cụ thể cho lệnh init. Các agent chạy trên Claude Code hoặc Codex nên bạn dùng tài khoản của các công cụ đó. Nếu bạn cần biết chính xác, xem README.md và thư mục docs/ trong repo.
Các "mod" của ruflo chạy với quyền của tài khoản bạn và không có sandbox. README khuyên đọc code trước khi cài. Hãy giữ Claude control ở mức mặc định read + ask cho tới khi bạn quen.
III.Cài đặt từng bước
README có ba đường. Đường chính là một lệnh init. Đường plugin nhẹ hơn, không thêm file vào dự án. Đường thứ ba dành cho Codex hoặc client MCP khác.
- Kiểm tra NodeChắc chắn Node.js từ 20 trở lên
- Chạy initGõ npx ruflo@latest init trong thư mục dự án
- Mở lại Claude CodeMở Claude Code ở cùng thư mục để nó nạp agent và hook
- Giao việc thửĐưa một tác vụ thật cho Claude Code dùng swarm
- Tuỳ chọnCài plugin hoặc console nếu muốn bảng điều khiển
A.Kiểm tra Node.js
Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và xem phiên bản Node. Lệnh node --version là lệnh phổ thông. Nếu số đầu nhỏ hơn 20, hãy cập nhật Node trước.
node --versionB.Chạy init trong thư mục dự án
Đi vào thư mục dự án của bạn bằng cd, rồi chạy lệnh từ README. Chỗ người mới hay vấp: phải đứng đúng thư mục dự án, vì init ghi file vào đó.
npx ruflo@latest initinit 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 các thư mục .claude/, .claude-flow/, file CLAUDE.md, helper và settings trong dự án.
Nếu muốn thiết lập từng bước theo dạng hỏi đáp, README có lệnh:
npx ruflo@latest init wizardMuốn xem trước mà chưa ghi gì (với Grok Build), README có cờ --dry-run, ví dụ npx ruflo init --grok --dry-run. README chỉ nêu cờ này trong phần Grok, nên với init thường bạn hãy xem tài liệu trước khi dùng.
C.Mở lại Claude Code
Mở Claude Code ở đúng thư mục vừa chạy init. README nói Claude Code sẽ nhận agent, hook, bộ nhớ và MCP server ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code, hãy đóng rồi mở lại.
D.Đường nhẹ: chỉ cài plugin
Đường 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 ngoài terminal):
/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, trên Claude Code 2.1.292 trở lên:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý README nói rõ: đường plugin chỉ cho slash command, một ít skill và định nghĩa agent. Nó không cài hook. Muốn dùng đủ vòng lặp như tài liệu mô tả thì dùng đường init.
E.Dùng với Codex hoặc client MCP khác
Không cần thiết lập dự án. Bạn cấu hình lệnh (command) là npx và đối số (arguments) như sau:
["-y", "ruflo@latest", "mcp", "start"]Tương đương một dòng lệnh:
npx -y ruflo@latest mcp startF.Chạy console riêng trong terminal
Không có Claude Code vẫn xem được bảng điều khiển:
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
Với đường init: sau khi lệnh chạy xong, kiểm tra thư mục dự án xem có .claude/, .claude-flow/ và file CLAUDE.md hay chưa. Rồi mở lại Claude Code và gõ:
/rufloNếu console hiện ra là cài đã thành công. README hướng dẫn trình tự npx ruflo init, khởi động lại Claude Code, rồi /ruflo.
Với đường plugin: gõ /plugin trong Claude Code để mở danh sách và xem các mod có nằm trong dòng "active mods" không. Trong console, lệnh /ruflo market mở Plugin Catalog, nơi có nút cài, bật, tắt và cập nhật từng plugin (mỗi hành động đều hỏi lại bạn).
Với đường MCP: client của bạn cần khởi động được server bằng lệnh npx -y ruflo@latest mcp start mà không báo lỗi. README chưa mô tả màn hình kết quả cụ thể cho trường hợp này, nên bạn xem thêm tài liệu trong repo nếu cần.
V.Dùng vào việc thật
A.Lập trình viên: rà soát cả repo trước khi giao
Bạn vừa nhận một dự án cũ và chưa biết chỗ nào dễ hỏng. Sau khi chạy init và mở lại Claude Code, bạn đưa đúng câu lệnh mẫu trong 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: một đội 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 vẫn nên tự đọc lại diff trước khi gộp vào nhánh chính.
Model viết code, còn harness cho nó công cụ, bộ nhớ và giới hạn để làm việc thật.
Ông T
B.Người quản lý nhóm: theo dõi agent và chi phí bằng console
Bạn là trưởng nhóm kỹ thuật, muốn biết AI đang làm gì và tốn bao nhiêu. Cài ruflo-console, mở /ruflo, bạn xem workflow, agent, model, token và chi phí cạnh Claude Code. Khi một lần chạy thất bại, bạn mở log, tìm kiếm rồi so sánh với lần trước. Plugin ruflo-cost-tracker theo README còn theo dõi lượng token dùng, đặt ngân sách và cảnh báo chi phí.
C.Thử cho Claude điều khiển console một cách an toàn
README có một bài tập nhỏ mà bạn làm được ngay:
- Mở
/ruflo, vào Settings → Claude control, chọn write + ask. - Gõ cho 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 đang chờ.
- Kiểm tra Missions có mục tiêu đó và Overview ghi lại hành động.
Lưu ý: tạo mission không có nghĩa tính năng dark mode đã được làm. Nếu muốn dừng, bấm Take back control; các lệnh sau đó của Claude sẽ bị từ chối cho tới khi bạn khôi phục quyền.
D.Dùng Codex hoặc công cụ khác qua MCP
Bạn không dùng Claude Code mà dùng Codex. Bạn khai báo MCP server với lệnh npx và đối số -y ruflo@latest mcp start. Từ đó client của bạn gọi được các công cụ của ruflo mà không phải cài gì vào dự án.
VI.Lỗi hay gặp và cách xử lý
A.Báo lỗi vì Node quá cũ
package.json yêu cầu Node từ 20 trở lên. Nếu máy bạn cài Node cũ hơn, lệnh npx có thể lỗi hoặc chạy sai. Cách xử lý: chạy node --version, cập nhật lên bản 20 hoặc mới hơn rồi chạy lại npx ruflo@latest init.
B.Claude Code không thấy agent hay hook sau khi init
README nói Claude Code nhận các thành phần này ở lần khởi động kế tiếp. Hãy đóng hẳn Claude Code rồi mở lại ở đúng thư mục vừa chạy init. Nếu vẫn không thấy, kiểm tra xem bạn có đứng nhầm thư mục khi chạy lệnh không.
C.Lệnh /plugin không nhận hoặc không cài được
Đường plugin cần Claude Code từ 2.1.287 trở lên, và lệnh claude plugin install ở terminal cần 2.1.292 trở lên. Cập nhật Claude Code rồi thử lại, sau đó gõ /reload-plugins.
D.Plugin chạy hai lần, lệnh bị nhân đôi
README cảnh báo với các plugin bên ngoài như agentic-qe-fleet, agentdb và agentic-flow: chỉ cài từ một marketplace (hoặc của chính nó, hoặc của ruflo). Nếu bật từ cả hai nơi, mod và lệnh sẽ nạp hai lần. Hãy gỡ một bên.
E.Claude bị từ chối khi điều khiển console
Đây là hành vi có chủ đích. Mức quyền mặc định là read + ask, và hành động vượt quyền sẽ bị từ chối. Nếu cần tạo mission, nâng lên write trong Settings → Claude control. Chỉ nâng khi bạn hiểu mình đang cho phép gì.
VII.Có nên dùng không
Điểm mạnh. Cài đặt gọn: một lệnh npx là có cả hệ agent, hook và bộ nhớ. Có nhiều lựa chọn đường cài, từ nhẹ (plugin) đến đầy đủ (init). Cơ chế quyền rõ ràng, mặc định thận trọng. Dự án giấy phép MIT, hiện có khoảng 81.582 sao, và còn được cập nhật trong vài tháng gần đây.
Giới hạn. Hệ thống rất lớn: README nhắc 406 công cụ MCP và 61 lệnh CLI, nhiều plugin. Người mới dễ choáng. Phần "tự học" của ruflo là mô hình khái niệm, README tự nói vẫn cần embedding và module cấu hình. Các video demo trong README dùng dữ liệu mẫu, README cũng nói chúng không chứng minh việc swarm hay bộ nhớ đã hoàn thành công việc thật. Hãy tự thử trên một dự án nhỏ trước.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần Claude Code làm việc đơn giản trên vài file, bản thân Claude Code đã đủ, thêm ruflo sẽ làm dự án thêm file và phức tạp. Nếu bạn không muốn thêm file vào dự án, hãy dùng đường plugin. Nếu bạn cần bảo mật chặt, hãy đọc kỹ code của mod trước khi cài vì chúng không chạy trong sandbox.
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 tự do. Tuy nhiên ruflo chạy trên Claude Code hoặc Codex, nên chi phí dùng model vẫn tính theo tài khoản của các công cụ đó. Tư liệu chưa nêu bảng giá cụ thể.
ruflo cần Node phiên bản nào?
`package.json` yêu cầu Node từ 20.0.0 trở lên. Bạn kiểm tra bằng lệnh `node --version` trước khi chạy `npx ruflo@latest init`.
Cài ruflo có làm thay đổi dự án của tôi không?
Có, nếu dùng `npx ruflo@latest init`: README nói nó thêm các thư mục `.claude/`, `.claude-flow/`, file `CLAUDE.md`, helper và settings. Nếu không muốn thêm file, bạn dùng đường plugin trong Claude Code, theo README là không thêm file nào vào workspace.
ruflo có dùng được với Codex, không chỉ Claude Code?
Được. README nói Codex và các MCP client khác dùng được bằng cách cấu hình lệnh `npx` với đối số `-y`, `ruflo@latest`, `mcp`, `start`. Bạn cũng có thể chạy `npx ruflo@latest init wizard` để thiết lập dự án theo từng bước.
Claude có tự làm bậy trong console của ruflo được không?
README mô tả cơ chế kiểm soát: bạn chọn mức quyền read, write, manage hoặc full, và chọn ask hay auto. Mặc định là read + ask. Các hành động liên quan mạng, chi tiền hay phá huỷ vẫn cần xác nhận ngay cả ở chế độ auto, và có nút Take back control để dừng.
ruflo có cần GPU hoặc cấu hình máy mạnh không?
Tư liệu không nêu yêu cầu phần cứng cho lệnh `init`. Chỉ có một plugin, `ruflo-ruvector`, được mô tả là tìm kiếm tăng tốc bằng GPU. Bạn xem thêm tài liệu trong repo nếu cần chắc chắn.
Chạy được trên Windows không?
Tư liệu không nêu rõ hệ điều hành hỗ trợ. Điều kiện được nói chắc chắn là Node từ 20 trở lên và Claude Code (với đường plugin) từ 2.1.287. Bạn nên thử trên một dự án nhỏ và xem README trong repo để biết thêm.


