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ụ bọc quanh Claude Code và Codex để nhiều agent phối hợp thành đội, có bộ nhớ qua nhiều phiên làm việc. Bạn dùng nó để giao việc lớn cho Claude Code mà không phải tự điều phối từng bước. Cài khá đơn giản, 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 "agent meta-harness": một lớp công cụ đặt quanh Claude Code và Codex để biến một trợ lý AI đơn lẻ thành một đội agent biết phối hợp, nhớ việc cũ và tự rút kinh nghiệm. Nói gọn theo cách README đặt: mô hình AI lo viết, còn ruflo lo phần còn lại, gồm công cụ, bộ nhớ, vòng lặp, giới hạn an toàn. Repo này trước đây có tên Claude Flow, và hiện có khoảng 81.600 sao cùng 9.600 fork trên GitHub.
Nếu bạn đã dùng Claude Code và thấy mỗi lần giao việc lớn thì phải tự chia nhỏ, tự nhắc lại bối cảnh, thì ruflo nhắm đúng chỗ đó. Sau khi chạy init, bạn vẫn dùng Claude Code như bình thường. Phần định tuyến tác vụ, học từ các lần làm tốt và phối hợp agent chạy ngầm bằng hook.
Đ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à đủ để thêm agent, hook, bộ nhớ và MCP server. Bạn không phải học hết hàng trăm công cụ. README nói thẳng là không cần học 406 công cụ MCP hay 61 lệnh CLI. Bài này đi từng bước để bạn cài được và thử được một việc thật.
ruvnet/ruflo
ruflo là bộ khung bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ lâu dài, hook và MCP server chỉ với một lệnh init.
I.ruflo làm được gì
Dưới đây là các nhóm tính năng chính, giải thích theo lợi ích thực tế.
Đội agent chuyên biệt (swarm). ruflo đi kèm 100+ agent chuyên biệt (README ở phần so sánh cách cài ghi 98 agent), và có thể điều phối chúng làm việc theo nhóm. Bạn có thể ra một yêu cầu như "review repo này, tìm module rủi ro nhất, viết test, rồi tóm tắt", và các agent chia nhau làm thay vì một agent làm tuần tự.
Bộ nhớ qua nhiều phiên. Agent không quên mọi thứ khi bạn đóng cửa sổ. ruflo có bộ nhớ vector (README nhắc đến HNSW, AgentDB, RAG) để lưu và truy xuất lại kinh nghiệm. Lợi ích: lần sau bạn làm việc tương tự, agent đã có sẵn bối cảnh.
Tự học từ việc đã làm. README mô tả vòng học: bộ nhớ đưa kinh nghiệm hữu ích quay lại phần định tuyến. README cũng lưu ý đây là sơ đồ 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.
Hook tự động. Sau init, hệ thống hook tự định tuyến tác vụ và phối hợp agent ở nền. Bạn không phải gõ lệnh riêng cho từng việc.
Bảng điều khiển (console) ngay cạnh Claude Code. Đây là "buồng lái" để theo dõi workflow, agent, mô hình, token và chi phí. Bạn có thể mở log từng agent, tìm kiếm, xem lại lỗi, so sánh các lần chạy. Mở bằng lệnh /ruflo trong Claude Code, hoặc chạy riêng ngoài terminal bằng npx ruflo tui.
Cho Claude điều khiển console, nhưng bạn đặt giới hạn. Trong Settings có mục Claude control với bốn mức: read, write, manage, full, và hai kiểu duyệt: ask hoặc auto. Mặc định hiện tại là read + ask. Các hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần bạn xác nhận, kể cả ở chế độ auto. Có nút Take back control để lấy lại quyền ngay.
Hệ plugin lớn. README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài) chia theo nhóm: điều phối, bộ nhớ, học máy, chất lượng code và test, bảo mật, kiến trúc, DevOps, mở rộng. Ví dụ ruflo-testgen tìm test còn thiếu và sinh test, ruflo-cost-tracker theo dõi token và đặt ngân sách, ruflo-security-audit quét lỗ hổng và CVE, ruflo-aidefence chặn prompt injection và phát hiện thông tin cá nhân.
Liên kết nhiều máy (federation). Agent trên các máy khác nhau có thể giao tiếp an toàn, README nói là không làm lộ dữ liệu. Phần này dành cho người cần nâng cao, người mới có thể bỏ qua.
Dùng được với nhiều công cụ. Ngoài Claude Code, README nói Codex và các MCP client khác cũng dùng được, và có lệnh npx ruflo init --grok cho Grok Build.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js từ phiên bản 20.0.0 trở lên.
package.jsoncủa repo yêu cầu như vậy, và các lệnh cài đều dùngnpxđi kèm Node. - Claude Code nếu bạn đi theo đường chính. Muốn cài theo kiểu plugin thì cần Claude Code 2.1.287 trở lên. Lệnh
claude plugin installtừ terminal 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 thư mục đó. - Nếu dùng Codex hoặc MCP client khác: chỉ cần client của bạn cho phép khai báo một MCP server bằng lệnh và tham số.
README phần đầu không nói rõ về hệ điều hành, API key hay phần cứng cụ thể. Mình cũng không thấy yêu cầu GPU trong phần tư liệu mình có. Nếu bạn cần chắc chắn về Windows hoặc cấu hình key cho từng nhà cung cấp, hãy xem thư mục docs/ và file README.md 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 đưa vào sandbox. README khuyên đọc mã nguồn trước khi cài. Với console, hãy giữ mức Claude control thấp nhất đủ dùng, vì hành động tốn tiền hoặc phá huỷ vẫn cần bạn xác nhận.
III.Cài đặt từng bước
README đưa ra vài đường cài. Đường nên chọn cho người mới là lệnh init trong thư mục dự án. Đường plugin nhẹ hơn nhưng ít tính năng hơn.
- Kiểm tra NodeChắc chắn máy có Node 20 trở lên
- Mở terminal đúng thư mụcVào thư mục dự án bạn muốn dùng ruflo
- Chạy initMột lệnh npx thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude CodeKhởi động Claude Code trong cùng thư mục để nó nhận cấu hình
- Giao một việc thậtNhập một yêu cầu dùng swarm để thử
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:
node --versionKết quả phải là v20.0.0 hoặc cao hơn. Nếu thấp hơn 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. Đây là chỗ người mới hay vấp nhất.
B.Mở terminal trong thư mục dự án
Bạn phải đứng trong thư mục dự án thật, vì init ghi file vào đúng nơi bạn đang đứng. Ví dụ:
cd duong-dan/toi/thu-muc-du-anHãy thay duong-dan/toi/thu-muc-du-an bằng đường dẫn thật trên máy bạn.
C.Chạy lệnh init
Đây là lệnh chính trong 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 của README, nó tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, cùng file helper và settings. Nghĩa là dự án của bạn sẽ có thêm file, nên nếu dùng Git, hãy xem lại phần thay đổi trước khi commit.
Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README có một lệnh khác:
npx ruflo@latest init wizardD.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ác thành phần mới ở lần khởi động kế tiếp. Rồi thử một việc thật, ví dụ 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.E.Cách khác: chỉ cài plugin trong Claude Code
Đường này không thêm file nào vào dự án, nhưng chỉ cho lệnh gạch chéo, một vài skill và định nghĩa agent. Chạy bên 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, với Claude Code 2.1.292 trở lên, README ghi:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloBạn có thể cài thêm từng plugin lẻ khi cần, ví dụ:
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@rufloF.Cách khác: Codex hoặc MCP client khác
Không cần cài vào dự án. Trong phần cấu hình MCP của client, đặt command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Cách này tương đương chạy npx -y ruflo@latest mcp start.
G.Cách khác: chạy console ngoài Claude Code
npx ruflo tuiThêm --plain nếu bạn muốn in ra một khung hình duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Có vài dấu hiệu theo tư liệu:
- Sau
initvà khi mở lại Claude Code, dự án của bạn có các thư mục.claude/và.claude-flow/cùng fileCLAUDE.md. - Trong Claude Code, gõ
/ruflođể mở console. Nếu mở được, phần cài console đã ổn. - Với đường plugin, mở
/pluginvà xem các mod có xuất hiện ở dòng "active mods" không. - Thử một việc nhỏ qua console: đặt Claude control ở mức
write + ask, rồi bảo Claude tạo một "mission". Bạn xác nhận thao tác tạo, rồi kiểm tra mission xuất hiện ở trang Missions và hành động được ghi ở Overview.
Lưu ý README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Nó chỉ chứng minh Claude điều khiển được console.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo khả năng có trong README. Kết quả cụ thể phụ thuộc vào dự án và mô hình bạn dùng, nên hãy xem đây là gợi ý cách bắt đầu.
A.Lập trình viên mới nhận một repo lạ
Bạn vừa được giao một dự án cũ, không ai giải thích. Sau khi init và mở lại Claude Code, gõ 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: các agent rà soát, chỉ ra module rủi ro nhất, viết test cho nó và báo lại thay đổi. Bạn đọc bản tóm tắt thay vì lần mò từng file.
Bạn vẫn viết code như bình thường, ruflo lo phần điều phối ở phía sau.
Ông T
B.Chủ dự án muốn kiểm soát chi phí token
Bạn dùng AI nhiều và sợ hoá đơn phình ra. Cài thêm plugin theo dõi chi phí (từ README):
/plugin install ruflo-cost-tracker@rufloPlugin này theo dõi lượng token, cho đặt ngân sách và cảnh báo chi phí. Kết hợp với console (/ruflo) để nhìn token và chi phí ngay cạnh Claude Code.
C.Người phụ trách chất lượng cần bổ sung test
Dự án có nhiều hàm chưa được test. Cài plugin sinh test:
/plugin install ruflo-testgen@rufloTheo README, plugin này tìm test còn thiếu và tự sinh. Bạn đưa yêu cầu cho Claude Code như "tìm chỗ thiếu test trong thư mục này và bổ sung". Sau đó hãy chạy bộ test của dự án và đọc lại từng test trước khi giữ, vì test do AI sinh vẫn cần người xem.
D.Người dùng Codex hoặc công cụ MCP khác
Bạn không dùng Claude Code mà dùng một client MCP khác. Khai báo command npx với arguments ["-y", "ruflo@latest", "mcp", "start"] như phần cài đặt ở trên. Client sẽ gọi được các công cụ của ruflo mà không cần thêm file vào dự án.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx báo lỗi hoặc không chạy. Nguyên nhân hay gặp là Node cũ hơn yêu cầu. Chạy node --version, nếu dưới 20 thì nâng cấp Node rồi chạy lại.
Claude Code không thấy ruflo sau khi init. README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy tắt hẳn và mở lại Claude Code trong đúng thư mục bạn đã chạy init. Chạy init ở thư mục khác thì Claude Code ở thư mục này sẽ không thấy gì.
Lệnh /plugin không nhận hoặc cài plugin thất bại. Đường plugin cần Claude Code từ 2.1.287 trở lên, còn lệnh claude plugin install từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi thử lại, và chạy /reload-plugins sau khi cài.
Plugin chạy hai lần hoặc lệnh bị trùng. README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow: chỉ nên cài từ một marketplace. Cài từ cả hai thì mod và lệnh sẽ tải hai lần. Hãy gỡ một bên.
Tên công cụ MCP khác với tài liệu. Nếu bạn cài bằng plugin, các công cụ của ruflo-core có tên dạng mcp__plugin_ruflo-core_ruflo__memory_store, không phải tên ngắn như memory_store của đường CLI. Khi làm theo hướng dẫn nào đó, hãy để ý bạn đang dùng đường cài nào. Muốn có đầy đủ tên theo kiểu CLI thì dùng npx ruflo@latest init.
Console từ chối hành động của Claude. Đây là thiết kế, không phải lỗi. Hành động vượt mức quyền bạn đặt sẽ bị từ chối. Mở Settings → Claude control và nâng mức lên khi bạn thực sự muốn, nhớ rằng thao tác dùng mạng, tốn tiền và phá huỷ vẫn cần xác nhận.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Có sẵn rất nhiều agent và plugin. Có bộ nhớ qua các phiên, có console để nhìn được agent đang làm gì, và có cơ chế giới hạn quyền khá rõ ràng. Giấy phép MIT, và repo vẫ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: hàng chục plugin, hàng trăm công cụ. Người mới dễ choáng, nên hãy bắt đầu chỉ với init rồi dùng Claude Code như thường. Lệnh init thêm nhiều file vào dự án, nên cần xem lại trước khi commit. Phần "tự học" và "liên kết nhiều máy" là các tính năng nâng cao, README tự lưu ý nhiều phần là sơ đồ khái niệm hoặc chỉ minh hoạ bằng dữ liệu mẫu, không phải bằng chứng cho mọi kết quả. Mod chạy với quyền tài khoản của bạn và không có sandbox.
Khi nào chọn cách khác. Nếu bạn chỉ cần một agent làm vài việc nhỏ, Claude Code thuần đã đủ, không cần thêm lớp điều phối. Nếu dự án chứa dữ liệu nhạy cảm, hãy đọc kỹ SECURITY.md và mã của mod trước khi bật. Nếu bạn chỉ muốn thử, đường plugin (không thêm file vào dự án) là cách ít rủi ro hơn để làm quen.
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 mã nguồn dùng tự do. Tuy nhiên ruflo chạy trên Claude Code, Codex hoặc các nhà cung cấp AI khác, và chi phí của những dịch vụ đó là việc riêng. README có plugin theo dõi token và đặt ngân sách để bạn kiểm soát.
ruflo cần phiên bản Node nào?
package.json yêu cầu Node từ 20.0.0 trở lên. Bạn có thể kiểm tra bằng lệnh node --version trước khi chạy npx.
Cài ruflo bằng cách nhanh nhất là gì?
Mở terminal trong thư mục dự án và chạy npx ruflo@latest init, rồi mở lại Claude Code trong cùng thư mục. Lệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. Nếu không muốn thêm file nào, bạn có thể cài theo đường plugin trong Claude Code.
ruflo khác gì dùng Claude Code thuần?
Theo README, ruflo là lớp harness bọc quanh Claude Code và Codex, thêm các agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên, hook và guardrail bảo mật. Claude Code vẫn là nơi bạn làm việc, còn ruflo lo phần điều phối ở nền.
Có dùng được với Codex hoặc công cụ không phải Claude Code không?
Có. README nói Codex và các MCP client khác dùng được, bằng cách khai báo command npx với arguments -y, ruflo@latest, mcp, start. README cũng có lệnh init --grok cho Grok Build.
Cho Claude điều khiển console có nguy hiểm không?
Mặc định là mức read kèm ask, tức chỉ đọc và hỏi bạn trước. Hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận kể cả ở chế độ auto, và có nút Take back control để dừng ngay. Mod chạy với quyền tài khoản của bạn nên README khuyên đọc mã trước khi cài.
ruflo có cần GPU hay chạy được trên Windows không?
Phần tư liệu hiện có chưa nói rõ yêu cầu GPU hay hệ điều hành cụ thể. Các lệnh cài đều dựa trên Node và npx. Bạn nên xem thêm README.md và thư mục docs trong repo để chắc chắn.


