Ruflo: điều phối nhóm 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ớ và hook. Bạn chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án rồi mở lại Claude Code. Cài đặt không khó nếu máy đã có Node 20 trở lên và Claude Code.
Ruflo là một “agent harness”: lớp công cụ đặt quanh Claude Code hoặc Codex để mô hình AI không chỉ trả lời, mà còn có agent chuyên biệt, bộ nhớ, vòng lặp và các giới hạn kiểm soát. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, viết chủ yếu bằng TypeScript, giấy phép MIT. Hiện có khoảng 81.582 sao và 9.607 fork trên GitHub.
Tác giả dùng một công thức dễ nhớ: Agent = Model + Harness. Mô hình lo việc viết. Harness lo phần còn lại: đưa công cụ, giữ ngữ cảnh giữa các bước, nhớ qua nhiều phiên làm việc, và giúp kiểm tra kết quả. Ruflo là phần harness đó.
Ai nên dùng? Lập trình viên đã quen Claude Code và muốn giao việc lớn cho nhiều agent phối hợp. Người mới cũng thử được, vì README nói rõ bạn không cần học hết hàng trăm công cụ bên trong. Sau khi chạy init, bạn cứ dùng Claude Code bình thường, còn hệ thống hook sẽ tự định tuyến tác vụ ở phía sau. Điểm đáng giá nhất là cài chỉ bằng một lệnh, và có bảng điều khiển (console) để bạn nhìn thấy agent đang làm gì.
ruvnet/ruflo
Ruflo là lớp điều phối bọc quanh Claude Code và Codex: thêm agent chuyên biệt, bộ nhớ, hook và MCP server vào dự án chỉ với một lệnh npx.
I.Ruflo làm được gì
Dưới đây là những tính năng chính, giải thích theo lợi ích thực tế.
Nhóm agent phối hợp (swarm). Thay vì một agent làm tất cả, Ruflo cho nhiều agent tự phân vai và cùng xử lý một việc. README nói cách cài đầy đủ mang theo 98 agent, hơn 60 lệnh và 30 skill. Lợi ích: bạn có thể giao một việc lớn như “review cả repo” thay vì chia nhỏ từng file.
Bộ nhớ và học từ kinh nghiệm. Ruflo lưu lại những gì đã làm để lần sau dùng lại, kể cả qua các phiên khác nhau. Bộ nhớ này nền tảng là cơ sở dữ liệu vector. README lưu ý: phần truy xuất vector cục bộ chạy được mà 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, các hook tự định tuyến tác vụ và ghi nhận mẫu làm việc thành công. Bạn không phải gọi thủ công từng công cụ.
MCP server. Ruflo có MCP server, nên Codex hay bất kỳ MCP client nào khác cũng gọi được các công cụ của nó.
Console (bảng điều khiển) trong Claude Code. Gõ /ruflo để xem workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Bạn mở được log và kết quả của từng agent, tìm kiếm, xem lại và so sánh các lần chạy.
Cho Claude điều khiển console, nhưng bạn đặt giới hạn. Trong Settings → Claude control, bạn chọn mức 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 mức quyền sẽ bị từ chối, và các hành động liên quan mạng, chi tiêu hay phá huỷ vẫn phải xác nhận kể cả khi để auto.
Hệ thống plugin. 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 tập, kiểm thử, bảo mật, DevOps… Ví dụ ruflo-testgen tìm test còn thiếu và sinh test, ruflo-cost-tracker theo dõi token và cảnh báo chi phí, ruflo-aidefence chặn prompt injection và phát hiện dữ liệu cá nhân.
Liên kết nhiều máy (federation). Agent trên các máy khác nhau có thể trao đổi an toàn, theo README là không làm lộ dữ liệu.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu rõ những điều sau:
- Node.js từ 20.0.0 trở lên (theo
package.json). Bạn cần cónpxđi kèm Node. - Claude Code nếu muốn dùng đường cài chính. Riêng đường cài chỉ bằng plugin yêu cầu Claude Code 2.1.287 trở lên. Lệnh
claude plugin installngoài terminal cần 2.1.292 trở lên. - Nếu dùng Codex hoặc client MCP khác: client đó phải cho cấu hình một MCP server bằng lệnh và tham số.
- Một thư mục dự án để chạy
init.
Tư liệu không nói rõ về hệ điều hành hay yêu cầu phần cứng như GPU, nên mình không khẳng định gì ở hai điểm này. Về tài khoản và khoá API: README không nêu rõ cần loại nào cho việc cài Ruflo; bạn vẫn cần quyền dùng Claude Code hoặc Codex như bình thường để agent chạy được.
Các “mod” của Ruflo chạy với quyền tài khoản của bạn và không được cô lập (sandbox). README khuyên đọc code của mod trước khi cài. Hãy giữ Claude control ở mức mặc định read + ask, chỉ nâng quyền khi bạn thật sự cần.
III.Cài đặt từng bước
README có ba đường cài. Đường nhanh nhất là chạy init trong dự án.
- Mở terminal đúng thư mụcVào thư mục dự án của bạn
- Chạy initThêm agent, hook, bộ nhớ và MCP server vào dự án
- Mở lại Claude CodeClaude Code nạp cấu hình mới ở lần khởi động kế tiếp
- Giao một việc thậtDán câu lệnh mẫu để thử swarm
- Mở consoleGõ /ruflo để xem bảng điều khiển
A.Mở terminal đúng thư mục dự án
Mở terminal (PowerShell, Terminal hay cmd đều được) rồi chuyển vào thư mục dự án của bạn. Chỗ người mới hay vấp: chạy lệnh sai thư mục thì Ruflo sẽ thêm file vào nhầm chỗ. Hãy chắc mình đang đứng đúng trong thư mục dự án.
cd ten-thu-muc-du-anB.Chạy lệnh init
Lệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo README, nó tạo các mục như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings trong thư mục làm việc.
npx ruflo@latest initNếu muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh riêng:
npx ruflo@latest init wizardC.Mở lại Claude Code trong cùng thư mục
Claude Code sẽ nhận agent, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code thì hãy thoát rồi mở lại trong chính thư mục dự án.
D.Giao một việc thật
Dán câu mẫu này 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ờ Ruflo dùng một swarm để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi.
E.Mở console
Trong Claude Code, gõ lệnh sau để mở bảng điều khiển. Lưu ý: console là một plugin riêng, nên nếu gõ mà chưa thấy gì, hãy xem phần cài bằng plugin bên dưới.
/rufloF.Cách khác: chỉ cài plugin (không thêm file vào dự án)
Đường này cài công cụ lõi, console và các mod mà không thêm file nào vào dự án. Bạn gõ các lệnh sau 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, trên Claude Code 2.1.292 trở lên, README có lệnh này:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloSo sánh nhanh theo README: đường plugin nhẹ hơn, chỉ có lệnh slash, vài skill và định nghĩa agent, không có hook. Đường npx ruflo init mới là bản đầy đủ, README khuyên dùng cho việc nghiêm túc.
G.Cách khác: Codex hoặc client MCP khác
Bạn cấu hình command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]Nghĩa là client sẽ chạy 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ỳ từng client, bạn xem tài liệu client đó.
H.Cách khác: chạy console trong terminal thường
Console cũng chạy riêng, không cần Claude Code:
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
Theo tư liệu, có vài dấu hiệu để bạn tự kiểm tra:
- Sau
initvà khi mở lại Claude Code, dự án có thêm các thư mục như.claude/và.claude-flow/cùng fileCLAUDE.md. - Gõ
/ruflotrong Claude Code thì mở được console. - Với đường plugin: gõ
/pluginvà kiểm tra các mod xuất hiện trong dòng “active mods”. - Nếu chạy
npx ruflo tuithì khung bảng điều khiển hiện ngay trong terminal.
README không đưa ra một dòng chữ “thành công” cố định cho lệnh init, nên mình không bịa ra. Cách chắc nhất là thấy file mới trong dự án và mở được /ruflo.
V.Dùng vào việc thật
A.Dev nhận một repo lạ và cần biết chỗ nào rủi ro
Bạn vừa nhận bảo trì một dự án cũ, ít test. Sau khi chạy init và mở lại Claude Code, bạn dán câu lệnh 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ả bạn mong đợi: agent chỉ ra module rủi ro nhất, viết test cho module đó và báo lại những gì đã thay đổi. Hãy tự đọc và chạy lại các test đó trước khi tin, vì agent có thể viết sai.
Agent = Model + Harness: mô hình viết, còn harness giúp nó thật sự làm việc được.
Ông T
B.Người mới muốn nhìn tận mắt agent đang làm gì
Bạn không muốn agent chạy “trong bóng tối”. Hãy mở console bằng /ruflo. Theo README, bạn xem được workflow, agent, mô hình, token và chi phí. Bạn còn mở được log và kết quả từng agent để xem agent nào lỗi.
Nếu muốn thử cho Claude tự thao tác console, README có kịch bản an toàn: vào Settings → Claude control → chọn write + ask, rồi nhờ Claude:
Create a mission to add a dark mode toggle. Show me the mission and its status.Claude mở trang Missions và đặt mục tiêu; bạn xác nhận hành động tạo trong console. Sau đó kiểm tra mục Missions có mục tiêu mới và Overview ghi lại hành động. Lưu ý quan trọng của README: tạo “mission” không có nghĩa là tính năng dark mode đã được làm xong. Muốn dừng, bấm Take back control.
C.Chủ dự án muốn thêm test và theo dõi chi phí
Nếu bạn chỉ cần vài chức năng, hãy cài đúng plugin thay vì cả bộ. Ví dụ ruflo-testgen (tìm test còn thiếu và sinh test) và ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Cú pháp cài theo mẫu README, bạn thêm marketplace trước:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@rufloREADME chỉ ghi lệnh cho ruflo-core, ruflo-swarm, ruflo-rag-memory và ruflo-neural-trader; các plugin khác bạn cài theo cùng kiểu /plugin install <tên>@ruflo, và nên mở /plugin hoặc /ruflo market để xem danh mục và nút cài. Kết quả: bạn có thêm lệnh slash và định nghĩa agent tương ứng, mà không có file nào bị thêm vào dự án.
D.Người dùng Codex muốn dùng chung công cụ
Bạn không dùng Claude Code mà dùng Codex. Hãy trỏ Codex tới MCP server của Ruflo bằng command npx và các tham số -y, ruflo@latest, mcp, start như ở phần cài đặt. Từ đó các công cụ của Ruflo hiện ra như công cụ MCP bình thường trong Codex. Muốn thiết lập theo từng bước hỏi đáp, chạy npx ruflo@latest init wizard.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx báo lỗi phiên bản hoặc không chạy. Ruflo yêu cầu Node từ 20.0.0 trở lên. Hãy kiểm tra bằng node --version, nếu thấp hơn thì nâng cấp Node rồi chạy lại.
Mở Claude Code nhưng không thấy agent hay công cụ 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 Claude Code, rồi mở lại trong đúng thư mục đã chạy init. Với cài bằng plugin, thử /reload-plugins.
Lệnh /plugin hoặc claude plugin install không nhận. Đường plugin cần Claude Code từ 2.1.287, còn lệnh ngoài terminal cần 2.1.292. Hãy cập nhật Claude Code trước.
Plugin ngoài bị nạp hai lần. 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 (hoặc marketplace riêng của chúng, hoặc ruflo), không cài từ cả hai, nếu không mod và lệnh sẽ nạp hai lần.
Claude từ chối thao tác trong console. Đó là cơ chế bảo vệ. Hành động vượt quá mức quyền bạn đặt (read, write, manage, full) sẽ bị từ chối, và một số hành động như tiêu tiền hay phá huỷ luôn cần xác nhận. Nếu đúng ý bạn, hãy nâng mức quyền một cách có chủ ý; nếu thấy Claude làm quá tay, bấm Take back control.
VII.Có nên dùng không
Điểm mạnh. Cài đặt chỉ một lệnh. Có đường cài nhẹ không thêm file vào dự án. Bạn kiểm soát được mức quyền khi cho Claude điều khiển console. Hệ sinh thái rộng (agent, bộ nhớ, bảo mật, theo dõi chi phí), hoạt động cả với Claude Code lẫn Codex. 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. Dự án rất lớn: README nhắc tới hàng trăm công cụ MCP và hàng chục lệnh CLI, nên người mới dễ choáng nếu muốn hiểu hết. README cũng tự nói rõ một số video demo dùng dữ liệu mẫu hoặc replay khung hình, chúng không chứng minh swarm đã hoàn thành việc thật hay bộ nhớ đã nhớ lại đúng. Các mod chạy bằng quyền tài khoản và không được sandbox. Tư liệu chưa cho biết chi phí token thực tế cho một swarm, nên bạn cần tự theo dõi.
Khi nào chọn cách khác. Nếu bạn chỉ cần một trợ lý viết code đơn giản, dùng Claude Code hay Codex thuần là đủ, chưa cần thêm một lớp điều phối. Hãy thử Ruflo khi việc của bạn đủ lớn để cần nhiều agent, cần bộ nhớ giữa các phiên, hoặc cần nhìn rõ agent đang làm gì. Khuyến nghị của mình: thử trên một dự án nhỏ trước, giữ quyền ở mức read + ask, rồi mới 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. Tư liệu không nói gì về giá của Claude Code, Codex hay các nhà cung cấp mô hình mà agent gọi tới, nên chi phí đó bạn cần tự kiểm tra. Có plugin ruflo-cost-tracker để theo dõi token và cảnh báo chi phí.
Ruflo khác gì Claude Flow?
Theo README, Claude Flow chính là tên cũ: dự án nay đã đổi tên thành Ruflo, do rUv đặt. Gói npm hiện vẫn có tên claude-flow, còn lệnh khuyến nghị là npx ruflo@latest.
Cần cài gì trước khi dùng?
Cần Node.js từ phiên bản 20.0.0 trở lên. Nếu dùng đường plugin thì cần Claude Code 2.1.287 trở lên. Tư liệu chưa nêu yêu cầu phần cứng như GPU.
Dùng được với Codex hay chỉ với Claude Code?
Dùng được cả hai. Với Codex hoặc client MCP khác, bạn cấu hình command là npx và các tham số -y, ruflo@latest, mcp, start. README cũng nhắc tới tích hợp với Grok qua lệnh npx ruflo init --grok.
Cài Ruflo có làm lộn xộn dự án của tôi không?
Nếu chạy npx ruflo init thì có: README nói nó thêm .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings vào thư mục làm việc. Nếu không muốn thêm file nào, hãy dùng đường cài bằng plugin, theo README là không thêm file vào dự án.
Claude có tự ý làm bậy trong console không?
Mặc định chỉ ở mức read và phải hỏi bạn trước (ask). Hành động vượt mức quyền bị từ chối, còn hành động liên quan mạng, chi tiêu hay phá huỷ luôn cần xác nhận kể cả khi để auto. Bạn có thể bấm Take back control để dừng.
Có cần học hết các công cụ và lệnh của Ruflo không?
Không. README nói bạn không cần học hết hàng trăm công cụ MCP hay các lệnh CLI. Sau khi chạy init, bạn dùng Claude Code như bình thường và hệ thống hook sẽ tự định tuyến tác vụ, học từ mẫu thành công và phối hợp agent ở phía sau.


