Ruflo: điều phối nhiều 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 meta-harness: lớp công cụ bọc quanh Claude Code và Codex để nhiều agent phối hợp làm việc và nhớ được kinh nghiệm giữa các phiên. Bạn cài bằng một lệnh npx trong thư mục dự án, cần Node từ 20 trở lên. Với người mới, phần cài khá nhanh; phần dùng sâu thì rộng nên nên bắt đầu từ một việc nhỏ.
Ruflo là một bộ khung (harness) bọc quanh Claude Code và Codex. Nó thêm vào dự án của bạn các agent chuyên biệt, hook, bộ nhớ và một MCP server, để AI không chỉ trả lời từng câu mà còn biết chia việc, phối hợp và nhớ lại kinh nghiệm. Repo này hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.
Tác giả dùng một công thức dễ nhớ: agent = mô hình + harness. Mô hình lo phần viết. Harness cho nó công cụ, bộ nhớ, vòng lặp và các giới hạn an toàn để làm việc thật. Ruflo chính là phần harness đó. Nếu bạn đã dùng Claude Code và thấy mỗi phiên làm việc lại phải giải thích từ đầu, Ruflo nhắm đúng vào chỗ đau này.
Ai nên đọc bài này? Lập trình viên mới đang dùng Claude Code hoặc Codex, người làm kỹ thuật trong doanh nghiệp nhỏ muốn thử cho AI làm việc theo nhóm, hoặc bất kỳ ai tò mò về chuyện nhiều agent phối hợp. Điểm đáng giá nhất là bạn chỉ cần một lệnh để bắt đầu, sau đó 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, vì hook sẽ tự định tuyến tác vụ ở nền.
ruvnet/ruflo
Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent, bộ nhớ, hook và MCP server chỉ với một lệnh npx ruflo init.
I.Ruflo làm được gì
Dưới đây là các nhóm tính năng chính, kèm lợi ích thực tế khi dùng.
- Agent và swarm. Ruflo thêm nhiều agent chuyên biệt (README ghi 100+ agent; bảng so sánh cài đặt ghi 98 agent) và cho chúng phối hợp thành nhóm. Lợi ích: bạn giao một việc lớn như rà soát cả repo, thay vì tự chia nhỏ từng bước.
- Bộ nhớ qua nhiều phiên. Agent nhớ lại kinh nghiệm từ các tác vụ trước. Lợi ích: ít phải lặp lại bối cảnh dự án mỗi lần mở Claude Code.
- Học từ tác vụ thành công. Hệ thống định tuyến dùng lại những mẫu làm việc từng hiệu quả. README ghi đây là mô hình học ở mức khái niệm, và vẫn cần embedding cùng các module học được cấu hình.
- Hook tự động. Sau khi chạy init, hook sẽ định tuyến tác vụ và điều phối agent ở nền, bạn không phải gõ thêm lệnh.
- Bảng điều khiển (console). Một buồng lái cạnh Claude Code để theo dõi workflow, agent, mô hình, token và chi phí; xem log, tìm lỗi, phát lại và so sánh các lần chạy.
- Cho Claude điều khiển console có giới hạn. Bạn chọn mức quyền read, write, manage hoặc full, và chọn ask (hỏi trước) hoặc auto. Mặc định hiện là read + ask. Hành động liên quan mạng, chi tiền hoặc phá huỷ vẫn phải xác nhận ngay cả ở chế độ auto.
- Hệ plugin. Có 48 plugin (thêm 3 plugin bên ngoài) chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps, tài liệu. Ví dụ ruflo-testgen tìm test còn thiếu và tạo test, ruflo-cost-tracker theo dõi token và đặt ngân sách, ruflo-aidefence chặn prompt injection và phát hiện dữ liệu cá nhân.
- Federation. Agent trên các máy khác nhau có thể liên lạc an toàn với nhau. Đây là tính năng nâng cao, người mới chưa cần.
- Hỗ trợ nhiều nền tảng. Ngoài Claude Code, README nhắc Codex và các MCP client khác, kèm tuỳ chọn cho Grok Build.
II.Cần chuẩn bị gì
Tư liệu của repo nêu những điều sau, mình không thêm gì ngoài đó:
- Node.js từ 20.0.0 trở lên. package.json yêu cầu như vậy, và các lệnh cài đều dùng npx đi kèm Node.
- Claude Code nếu bạn muốn dùng đường cài đặt chính. Riêng đường cài chỉ bằng plugin cần Claude Code 2.1.287 trở lên; lệnh plugin chạy từ terminal cần 2.1.292 trở lên.
- Hoặc Codex / MCP client khác nếu bạn dùng các công cụ đó. Khi đó bạn trỏ client tới lệnh MCP của Ruflo (xem phần cài đặt).
- Một thư mục dự án để chạy lệnh init. Ruflo sẽ thêm file vào thư mục này.
Về hệ điều hành, phần cứng, tài khoản hay API key: phần README mình có trong tay chưa nói rõ yêu cầu cụ thể. Bạn nên xem thêm README đầy đủ và thư mục docs trong repo trước khi dùng cho việc quan trọng.
Mod của Ruflo chạy với quyền tài khoản của bạn và không nằm trong sandbox. README khuyên đọc code trước khi cài. Hãy làm đúng như vậy, đặc biệt trên máy có dữ liệu công việc thật.
III.Cài đặt từng bước
- Mở terminalVào đúng thư mục dự án của bạn
- Chạy initMột lệnh npx để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude CodeMở trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thậtDán một câu lệnh mẫu để thử swarm
- Tuỳ chọn: cài plugin hoặc consoleDùng /plugin và /ruflo trong Claude Code
A.Mở terminal đúng thư mục dự án
Lệnh init ghi file vào thư mục hiện tại, nên chỗ này người mới hay vấp nhất. Hãy mở terminal rồi chuyển vào thư mục dự án của bạn trước. Nếu chưa có dự án, hãy tạo một thư mục thử nghiệm riêng để không đụng vào công việc thật.
cd duong-dan-toi-thu-muc-du-an-cua-banThay phần sau cd bằng đường dẫn thật trên máy bạn.
B.Chạy lệnh init
Đây là lệnh chính trong README. Nó thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án.
npx ruflo@latest initBảng so sánh trong README cho biết lệnh này tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md cùng một số file hỗ trợ và settings. Nếu thư mục của bạn đã có CLAUDE.md riêng, hãy sao lưu trước khi chạy.
Muốn thiết lập theo kiểu hỏi đáp từng bước, README có lệnh sau:
npx ruflo@latest init wizardC.Mở lại 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 kế tiếp. Vì vậy nếu Claude Code đang mở, hãy đóng rồi mở lại trong đúng thư mục dự án.
D.Giao thử một việc thật
README gợi ý dán câ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.Câu này nhờ một swarm rà soát repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn có thể viết tiếng Việt, nhưng mình chỉ chép đúng câu mẫu của README ở đây.
E.Tuỳ chọn: chỉ cài plugin vào Claude Code
Nếu bạn không muốn thêm file nào vào dự án, README có đường cài chỉ bằng plugin (cần Claude Code 2.1.287 trở lên). Gõ các lệnh này bên trong Claude Code, không phải ở 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, có lệnh thay thế cho một plugin:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloBảng so sánh của README nói đường plugin cho bạn lệnh slash và định nghĩa agent mà không thêm file vào workspace, nhưng không cài hook. Còn đường npx init cho trải nghiệm đầy đủ: agent, lệnh, skill, MCP server, hook và daemon. README khuyên dùng đường init cho việc nghiêm túc.
F.Tuỳ chọn: dùng với Codex hoặc MCP client khác
Trong client của bạn, cấu hình command là npx và arguments là mảng sau:
["-y", "ruflo@latest", "mcp", "start"]Nghĩa là client sẽ tự chạy lệnh tương đương npx -y ruflo@latest mcp start để khởi động MCP server của Ruflo. Chỗ nhập cấu hình khác nhau tuỳ client, bạn xem tài liệu của client đó.
G.Tuỳ chọn: chạy console trong terminal thường
Console cũng chạy độc lập, không cần Claude Code:
npx ruflo tuiREADME nói thêm cờ --plain để in ra một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Theo README, có vài dấu hiệu để biết cài thành công:
- Sau init, thư mục dự án có thêm các mục như .claude/, .claude-flow/ và CLAUDE.md.
- Mở lại Claude Code trong thư mục đó, rồi gõ
/ruflonếu bạn đã cài console. README cho biết lệnh này mở bảng điều khiển. - Với đường plugin, mở
/pluginvà xem plugin có xuất hiện trong dòng mod đang hoạt động hay không. - Thử câu lệnh mẫu về swarm ở phần trên và xem Claude Code có phản hồi theo hướng phối hợp agent không.
README không mô tả một dòng chữ cụ thể kiểu 'cài thành công' trong terminal, nên mình không bịa ra. Cách kiểm tra chắc nhất là các dấu hiệu trên.
V.Dùng vào việc thật
Các tình huống dưới đây bám đúng khả năng được README mô tả. Kết quả thực tế sẽ tuỳ dự án và mô hình bạn dùng.
A.Dev mới nhờ rà soát một repo lạ
Bạn vừa nhận một dự án chưa quen. Sau khi chạy init và mở lại Claude Code, dán đúng 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ả mong đợi: Claude chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Hãy đọc lại test do AI viết trước khi gộp vào nhánh chính.
Agent = mô hình + harness: mô hình viết, 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 phụ trách kỹ thuật theo dõi token và chi phí
Bạn lo AI đốt token mà không ai biết. Cài console và plugin chi phí, rồi theo dõi trong cùng màn hình:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-console@ruflo
/reload-plugins
/rufloREADME nói console hiển thị workflow, agent, mô hình, token và chi phí cạnh Claude Code. Nhóm DevOps còn có plugin ruflo-cost-tracker để theo dõi token, đặt ngân sách và cảnh báo chi phí. README liệt kê plugin này nhưng bài này không có lệnh cài riêng cho nó ngoài mẫu /plugin install <tên>@ruflo.
C.Thử cho Claude tạo một mission, nhưng bạn giữ quyền
Đây là bài thử an toàn mà README mô tả. Trong console /ruflo, vào Settings, chọn Claude control rồi đặt mức write + ask. Sau đó nhờ Claude:
Create a mission to add a dark mode toggle. Show me the mission and its status.Claude sẽ mở mục Missions và đặt mục tiêu, còn bạn xác nhận hành động tạo trong console. Kiểm tra xem Missions có mục tiêu đó và Overview có ghi lại hành động khô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 và các lệnh gọi sau đó của Claude sẽ bị từ chối.
D.Nhóm nhỏ dùng Codex hoặc công cụ MCP khác
Bạn không dùng Claude Code mà dùng Codex hay một MCP client khác. Chỉ cần trỏ client tới lệnh MCP của Ruflo (command là npx, arguments như phần cài đặt ở trên). Kết quả: client đó gọi được các công cụ của Ruflo mà không cần thiết lập dự án. Nếu cần thiết lập có hướng dẫn, chạy npx ruflo@latest init wizard.
VI.Lỗi hay gặp và cách xử lý
Claude Code không thấy agent hay lệnh mới. Nguyên nhân thường gặp là chưa mở lại Claude Code sau init, hoặc mở ở thư mục khác. Hãy đóng hẳn rồi mở lại trong đúng thư mục dự án. Với đường plugin, gõ /reload-plugins.
Lệnh /plugin báo không hợp lệ hoặc không tìm thấy plugin. Đường plugin cần Claude Code 2.1.287 trở lên (lệnh từ terminal cần 2.1.292 trở lên). Hãy cập nhật Claude Code rồi thử lại.
npx báo lỗi hoặc phiên bản Node cũ. package.json yêu cầu Node từ 20.0.0. Kiểm tra bằng node --version và nâng cấp nếu thấp hơn. Đây là lỗi rất dễ gặp với công cụ npm nói chung.
File CLAUDE.md hoặc cấu hình cũ bị thay đổi sau init. Ruflo thêm .claude/, .claude-flow/ và CLAUDE.md vào dự án. Nếu bạn đã có file riêng, hãy sao lưu hoặc dùng git để xem phần thay đổi. Với Grok, README có cờ --dry-run để xem trước (npx ruflo init --grok --dry-run). Mình chưa thấy README ghi cờ này dùng được cho các lệnh init khác, nên đừng tự giả định.
Lo ngại về quyền hạn khi Claude điều khiển console. Giữ mức mặc định read + ask và chỉ nâng khi cần. Các hành động liên quan mạng, chi tiền hoặc phá huỷ luôn cần bạn xác nhận. Nếu thấy có gì lạ, bấm Take back control.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Có sẵn nhiều agent và plugin, console theo dõi được chi phí, và có cơ chế phân quyền cho việc Claude điều khiển công cụ. Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây. README còn khá thẳng thắn: phần demo dùng dữ liệu mẫu và không chứng minh swarm hoàn thành việc thật hay trí nhớ hoạt động.
Giới hạn. Hệ thống rất rộng (hàng trăm công cụ MCP, hàng chục lệnh), nên người mới dễ choáng nếu cố học hết. Init thêm khá nhiều file vào dự án. Phần học và bộ nhớ vẫn cần embedding và các module được cấu hình. Mod chạy không sandbox với quyền tài khoản của bạn. Yêu cầu về hệ điều hành, API key và phần cứng, mình chưa thấy nêu rõ trong phần README có trong tay.
Nên chọn cách khác khi nào. Nếu bạn chỉ cần Claude Code trả lời câu hỏi đơn giản, hoặc dự án nhỏ và bạn muốn giữ thư mục thật gọn, chỉ dùng Claude Code thuần là đủ. Nếu muốn thử nhẹ, hãy cài đường plugin (không thêm file vào dự án) hoặc thử trên một thư mục thí nghiệm trước. Khi đã quen, mới chuyển sang đường init đầy đủ.
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 bọc quanh Claude Code và Codex, nên chi phí của các dịch vụ AI đó (nếu có) là chuyện riêng. README có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.
Ruflo cần phiên bản Node nào?
package.json yêu cầu Node từ 20.0.0 trở lên. Các lệnh cài trong README đều dùng npx. Riêng đường cài chỉ bằng plugin còn cần Claude Code 2.1.287 trở lên.
Cài bằng cách nào nhanh nhất?
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. README gọi đây là cách bắt đầu bằng một lệnh. Nếu muốn thiết lập có hướng dẫn, có lệnh npx ruflo@latest init wizard.
Dùng được với Codex hoặc công cụ khác ngoài Claude Code không?
Được theo README. Bạn cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"] trong Codex hoặc MCP client khác. README cũng nhắc cờ --grok cho Grok Build.
Cài plugin và chạy npx ruflo init khác nhau thế nào?
Đường plugin không thêm file nào vào workspace, cho lệnh slash, vài skill và agent, không cài hook. Đường npx init thêm .claude/, .claude-flow/, CLAUDE.md và cho trải nghiệm đầy đủ gồm agent, lệnh, skill, MCP server, hook và daemon. README khuyên dùng init cho việc nghiêm túc.
Cho Claude điều khiển console có an toàn không?
README mô tả mức quyền read, write, manage, full và chế độ ask hoặc auto; mặc định hiện là read + ask. 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ả ở auto, và có nút Take back control để dừng. Riêng mod thì chạy không sandbox với quyền tài khoản của bạn, nên nên đọc code trước khi cài.
Cần GPU hay chạy được trên Windows không?
Phần README mình có trong tay chưa nêu yêu cầu GPU hay danh sách hệ điều hành được hỗ trợ. Bạn nên xem README đầy đủ và thư mục docs trong repo để biết chắc.


