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 harness": lớp công cụ bao quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ lâu dài và máy chủ MCP. Bạn chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng bộ công cụ rất rộng nên nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một "agent meta-harness" cho Claude Code và Codex: một lớp công cụ bao quanh mô hình AI để nó làm việc có tổ chức hơn. Tác giả mô tả bằng một công thức ngắn: Agent = Model + Harness. Mô hình lo viết code, còn harness lo công cụ, bộ nhớ, vòng lặp và các giới hạn an toàn. Ruflo là phần harness đó.
Nếu bạn đang dùng Claude Code và thấy mỗi phiên làm việc đều phải giải thích lại từ đầu, hoặc muốn nhiều agent chia nhau việc thay vì một agent làm hết, thì đây là repo đáng thử. Repo hiện có khoảng 81.582 sao và 9.607 fork, giấy phép MIT, viết chủ yếu bằng TypeScript. Tác giả là Reuven Cohen (rUv), dự án khởi đầu với tên Claude Flow rồi đổi tên thành Ruflo.
Điểm đáng giá nhất là cách cài: một lệnh npx ruflo@latest init, sau đó 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 406 công cụ MCP hay 61 lệnh CLI. Sau khi init, hệ thống hook tự định tuyến tác vụ và điều phối agent ở phía sau.
ruvnet/ruflo
Ruflo là bộ khung (harness) thêm agent, swarm, bộ nhớ, hook và MCP server cho Claude Code và Codex; cài bằng một lệnh npx.
I.Ruflo làm được gì
Bạn không cần dùng hết. Dưới đây là những phần có ích nhất cho người mới, theo đúng những gì README mô tả.
A.Thêm agent, lệnh, kỹ năng và hook vào dự án
Sau init, dự án của bạn có thêm agent, hook, bộ nhớ và một MCP server. Theo bảng so sánh trong README, cách cài bằng CLI cho bạn 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon. Claude Code sẽ nhận các thứ này ở lần khởi động kế tiếp. Lợi ích thực tế: bạn có sẵn "đội" agent chuyên biệt mà không phải tự viết từng file cấu hình.
B.Swarm: nhiều agent chia việc
Thay vì một agent làm tuần tự, Ruflo cho các agent tự tổ chức thành swarm (đàn, nhóm). Ví dụ trong README là yêu cầu "dùng một swarm của ruflo để rà soát repo, tìm module rủi ro nhất, viết test và tóm tắt thay đổi". Với việc lớn, chia nhóm giúp bạn đỡ phải điều phối từng bước.
C.Bộ nhớ qua nhiều phiên
Ruflo có bộ nhớ để agent nhớ giữa các phiên làm việc, và các plugin như ruflo-agentdb, ruflo-rag-memory, ruflo-rvf phục vụ việc lưu, truy xuất và khôi phục. README lưu ý phần "tự học" chỉ là mô hình khái niệm: truy xuất vector cục bộ có thể chạy không cần LLM, nhưng embedding và các module học đã cấu hình vẫn cần có.
D.Bảng điều khiển ngay trong Claude Code
Plugin ruflo-console là một "cockpit": theo dõi workflow, agent, mô hình, token và chi phí bên cạnh Claude Code. Bạn mở bằng lệnh /ruflo. Có thể xem log agent, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Bảng điều khiển cũng chạy riêng ngoài Claude Code bằng npx ruflo tui.
E.Cho Claude lái, 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. Hành động vượt quyền sẽ bị từ chối, còn hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận kể cả ở chế độ auto. Nút "Take back control" dừng ngay quyền điều khiển của Claude.
F.Hơn 48 plugin theo nhóm việc
README liệt kê 48 plugin, chia theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ, học và trí tuệ, kiểm thử (testgen, browser), bảo mật (security-audit, aidefence), kiến trúc, DevOps (theo dõi chi phí token) và công cụ tạo plugin riêng. Bạn chỉ cài cái mình cần.
G.Dùng được với Codex và client MCP khác
Không chỉ Claude Code. Codex và các client MCP khác có thể trỏ vào npx -y ruflo@latest mcp start. README cũng 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ừ 20.0.0 trở lên.
package.jsoncủa gói yêu cầu như vậy, và các lệnh đều chạy quanpx. - Claude Code (hoặc Codex, hoặc một client MCP khác) nếu bạn muốn dùng Ruflo ở vai trò harness.
- Claude Code 2.1.287 trở lên nếu chọn cách cài bằng plugin. Lệnh cài từ terminal (
claude plugin install ...) cần bản 2.1.292 trở lên. - Một thư mục dự án để chạy
init.
Tư liệu không nói rõ yêu cầu về hệ điều hành, phần cứng hay API key riêng cho phần cài đặt cơ bản. Bản thân Claude Code hay Codex vẫn cần tài khoản của chúng như bình thường. Nếu bạn bật các module học hoặc embedding, README nói chúng "vẫn cần có" nhưng không nêu chi tiết cần gì, nên hãy xem thêm trong thư mục docs/ của repo.
III.Cài đặt từng bước
Có ba đường: init bằng CLI (đầy đủ nhất), plugin cho Claude Code (nhẹ hơn, không thêm file vào dự án), và cấu hình MCP cho client khác. Mình hướng dẫn đường CLI trước vì README khuyên nó cho việc dùng thật.
- Kiểm tra NodeĐảm bảo máy có Node 20 trở lên
- Mở terminal trong dự ánVào đúng thư mục bạn muốn dùng Ruflo
- Chạy initChạy một lệnh để thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude CodeKhởi động Claude Code trong cùng thư mục
- Giao một tác vụ thậtGõ yêu cầu mẫu để thử swarm
A.Kiểm tra Node
Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và chạy:
node --versionKết quả phải là v20 trở lê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 đúng thư mục dự án
Lệnh init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong thư mục dự án của mình, không phải thư mục người dùng chung chung. Ví dụ:
cd duong-dan-toi-du-an-cua-banThay duong-dan-toi-du-an-cua-ban bằng đường dẫn thật của bạn.
C.Chạy init
Đây là lệnh chính trong README:
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh trong README, bạn sẽ thấy xuất hiện các mục như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings. Nếu thư mục dự án của bạn đã có CLAUDE.md riêng, hãy sao lưu hoặc dùng git để xem lại thay đổi sau khi chạy.
Muốn cài có hướng dẫn từng câu hỏi, README có lệnh:
npx ruflo@latest init wizardD.Mở lại Claude Code và giao tác vụ
Mở Claude Code trong cùng thư mục. Nếu nó đang mở sẵn, hãy thoát và mở lại để nhận cấu hình mới. Rồi thử yêu 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.Bạn có thể viết bằng tiếng Việt nếu muốn, nhưng câu mẫu trên là câu đã được README dùng.
E.Cách khác: cài bằng plugin Claude Code
Cách này không thêm file nào vào dự án. Chạy các lệnh sau 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
/rufloGiải thích nhanh: lệnh đầu thêm "chợ" plugin của Ruflo, ba lệnh install cài lõi, bảng điều khiển và mods, /reload-plugins nạp lại, còn /ruflo mở bảng điều khiển. Nếu từ terminal và Claude Code bản 2.1.292 trở lên, README cho phép:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloMods chạy với quyền của tài khoản bạn và không bị sandbox. README khuyên đọc mã của mod trước khi cài. Hãy làm đúng như vậy, nhất là trên máy có dữ liệu công việc quan trọng.
F.Cách khác: Codex hoặc client MCP khác
Không cần thiết lập 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"]Bạn cần tìm đúng chỗ khai báo MCP server trong client của mình. README không hướng dẫn riêng cho từng client.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh "kiểm tra" riêng, nhưng có vài dấu hiệu rõ ràng theo tư liệu:
- Sau
init, thư mục dự án có thêm.claude/,.claude-flow/vàCLAUDE.md. - Mở lại Claude Code, gõ
/ruflođể mở bảng điều khiển. README gợi ý chu trình:npx ruflo init, khởi động lại Claude Code, rồi/ruflo. - Với cách cài plugin, gõ
/pluginđể xem các mod có xuất hiện trong dòng "active mods". - Chạy
npx ruflo tuiđể mở bảng điều khiển độc lập trong terminal. Thêm--plainđể in ra đúng một khung, tiện cho script.
Thử nhanh nhất: giao tác vụ mẫu ở trên và xem Claude Code có dùng agent hoặc swarm của Ruflo hay không. Nếu bạn muốn kiểm tra mà chưa tin tưởng việc thay đổi file, các lệnh như npx ruflo init --grok --dry-run cho thấy ý tưởng "xem trước": README nói cờ --dry-run dùng để xem trước phần ghi file (ở đó là cho Grok).
V.Dùng vào việc thật
README nhấn mạnh Ruflo mạnh nhất khi bạn giao cho nó việc có nhiều bước. Dưới đây là các tình huống bám đúng khả năng được mô tả.
A.Dev mới nhận một repo lạ cần rà soát nhanh
Bạn vừa nhận một dự án chưa quen. Chạy npx ruflo@latest init trong thư mục dự án, mở Claude Code và gõ:
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 chia việc tìm module rủi ro, viết test cho nó và tóm tắt những gì đã đổi. Bạn đọc phần tóm tắt, xem diff trước khi giữ lại thay đổi nào.
Agent không chỉ chạy, mà còn biết phối hợp với nhau.
Ông T
B.Người làm sản phẩm muốn theo dõi agent và chi phí
Bạn không rành code nhưng muốn biết AI đang làm gì và tốn bao nhiêu token. Cài bằng đường plugin: thêm marketplace rồi cài ruflo-console, ruflo-mods, nạp lại bằng /reload-plugins và gõ /ruflo. Bảng điều khiển hiển thị workflow, agent, mô hình, token và chi phí bên cạnh Claude Code. Nhờ vậy bạn nhìn thấy thay vì đoán.
C.Để Claude tạo "mission" trong bảng điều khiển, có kiểm soát
Đây là bài tập an toàn trong README. Làm theo thứ tự:
- Mở
/ruflo, vào Settings → Claude control, chọn write + ask. - Gõ: "Create a mission to add a dark mode toggle. Show me the mission and its status."
- Khi Claude mở mục Missions và đặt mục tiêu, bạn xác nhận hành động tạo.
- Kiểm tra Missions đã có mục tiêu và Overview đã ghi lại hành động.
Lưu ý README nói rõ: tạo mission không có nghĩa là tính năng đã được làm xong. Bạn đang tập cách giao quyền có giới hạn, không phải xem phép màu.
D.Dùng Ruflo từ Codex hoặc công cụ khác
Nếu nhóm bạn dùng Codex hoặc một client MCP khác, cấu hình command npx với arguments ["-y", "ruflo@latest", "mcp", "start"]. Client đó có thể gọi các công cụ của Ruflo (bộ nhớ, swarm…) mà không cần thêm file vào dự án.
VI.Lỗi hay gặp và cách xử lý
Các lỗi dưới đây là những điểm rất dễ gặp với loại công cụ này, xây trên các yêu cầu có trong tư liệu.
A.npx báo lỗi hoặc lệnh không chạy
Thường do Node cũ hơn yêu cầu (cần 20 trở lên) hoặc chưa cài Node. Chạy node --version, nâng cấp Node nếu cần rồi chạy lại lệnh init.
B.Mở Claude Code mà không thấy gì mới
README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy thoát hẳn rồi mở lại trong đúng thư mục đã chạy init. Nếu dùng plugin, thử /reload-plugins. Nếu vẫn chưa có, hãy kiểm tra xem bạn có đang đứng đúng thư mục dự án khi chạy init không.
C.Lệnh /plugin install hoặc claude plugin install không nhận
Cách plugin cần Claude Code từ 2.1.287 trở lên, và lệnh từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước.
D.Plugin chạy lặp hoặc xung đột
README cảnh báo với các plugin bên ngoài như agentic-qe-fleet, agentdb, agentic-flow: chỉ cài từ một marketplace duy nhất. Nếu bật từ cả hai nơi, mod và lệnh có thể bị nạp hai lần.
E.Chi phí và quyền hạn vượt ý muốn
Swarm nhiều agent có thể dùng nhiều token hơn một agent đơn. Giữ mức quyền thấp (read hoặc write với chế độ ask), bật theo dõi chi phí và xem bảng điều khiển. Nếu thấy agent làm điều bạn không muốn, dùng nút "Take back control".
VII.Có nên dùng không
Điểm mạnh. Cài đặt bằng một lệnh, giấy phép MIT, repo còn được cập nhật trong vài tháng gần đây. Bạn có sẵn agent, bộ nhớ, bảng điều khiển và hệ thống phân quyền để giao việc có giới hạn. Hỗ trợ cả Claude Code, Codex và client MCP khác nên không bị khoá vào một công cụ.
Giới hạn. Bộ công cụ rất rộng (48 plugin, hàng trăm công cụ MCP), nên người mới dễ choáng. README còn nói thẳng nhiều phần chỉ là mô hình khái niệm hoặc dùng dữ liệu mẫu trong bản demo, không phải bằng chứng việc đã hoàn thành. Cài bằng init thêm khá nhiều file vào dự án. Tư liệu chưa nêu rõ yêu cầu hệ điều hành hay phần cứng.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần Claude Code làm vài việc nhỏ, dùng Claude Code thuần là đủ. Nếu bạn muốn thử nhẹ, cài một plugin lẻ (zero file trong dự án) rồi mới quyết định có chạy init đầy đủ hay không. Nếu bạn quản lý dữ liệu nhạy cảm, hãy đọc kỹ mã mod và mức quyền trước khi bật.
Lời khuyên của mình: chạy thử trên một dự án nhỏ, giữ mức quyền thấp, giao đúng một tác vụ như câu mẫu và xem kết quả trước khi mở rộng.
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 cùng 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à riêng. Tư liệu không nói gì thêm về gói trả phí của Ruflo.
Ruflo cần phiên bản Node nào?
File package.json yêu cầu Node từ 20.0.0 trở lên. Các lệnh cài đặt trong README đều chạy qua npx nên bạn cần Node và npm hoạt động bình thường.
Ruflo khác gì dùng Claude Code thuần?
Ruflo là lớp bao quanh Claude Code: thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook, MCP server và bảng điều khiển. README mô tả nó theo công thức Agent = Model + Harness, trong đó Ruflo là phần harness. Nếu bạn chỉ làm việc nhỏ, Claude Code thuần có thể đã đủ.
Cài bằng init và cài bằng plugin khác nhau thế nào?
Cách plugin không thêm file nào vào dự án và chỉ cho slash command, vài skill, định nghĩa agent. Cách `npx ruflo init` thêm .claude/, .claude-flow/, CLAUDE.md và cho vòng làm việc đầy đủ gồm hook, MCP server và daemon. README khuyên cách init cho dùng thật.
Dùng được với Codex hoặc công cụ khác ngoài Claude Code không?
Có. README nói Codex và các client MCP khác dùng được: đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. README cũng có lệnh init riêng cho Grok Build.
Cho Claude điều khiển bảng điều khiển có nguy hiểm không?
Bạn tự đặt mức quyền (read, write, manage, full) và chế độ duyệt (ask hoặc auto); mặc định hiện là read + ask. Hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận ngay cả khi ở auto, và có nút Take back control để dừng. Riêng mods thì không bị sandbox, nên cần đọc mã trước khi cài.
Có cần GPU hoặc cấu hình mạnh không?
Tư liệu không nêu yêu cầu phần cứng cho phần cài đặt cơ bản. Một số plugin nhắc đến tìm kiếm tăng tốc bằng GPU hoặc chạy mô hình cục bộ, nhưng đó là phần tuỳ chọn và chưa có thông tin chi tiết trong tư liệu này.


