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, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên làm việc, hook và máy chủ MCP. Bạn dùng nó để giao việc lớn cho một nhóm agent phối hợp thay vì một agent đơn lẻ. Cài khá dễ: chạy một lệnh npx trong thư mục dự án, cần Node từ 20 trở lên.
ruflo là một "agent harness" mã nguồn mở: lớp công cụ đặt quanh Claude Code và Codex để các AI agent có thêm công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát. Nói đơn giản, mô hình AI là người viết, còn ruflo là cái bàn làm việc đầy đủ đồ nghề để người đó làm việc cho ra việc. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.588 sao và 9.608 fork trên GitHub, giấy phép MIT.
Bạn nên xem ruflo nếu đang dùng Claude Code hoặc Codex và thấy một agent đơn lẻ làm chưa đủ: việc lớn cần chia nhỏ, cần nhớ lại những gì đã làm hôm trước, cần có người rà soát. Lập trình viên mới hay người làm kinh doanh có biết chút dòng lệnh đều thử được, vì cài đặt chỉ là một lệnh.
Điểm đáng giá nhất là tác giả nhấn mạnh 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 như bình thường; hook của ruflo tự định tuyến tác vụ, học từ các lần làm thành công và điều phối agent ở phía sau.
ruvnet/ruflo
ruflo là bộ khung (harness) thêm agent, bộ nhớ, hook và máy chủ MCP cho Claude Code và Codex, để nhiều agent phối hợp làm việc. Cài bằng một lệnh npx.
I.ruflo làm được gì
Dưới đây là những phần chính mà README nêu, kèm lợi ích thực tế.
- Nhóm agent (swarm). ruflo có sẵn nhiều agent chuyên biệt và cho chúng phối hợp như một đội. Lợi ích: bạn giao một việc như "rà soát repo, viết test, tóm tắt thay đổi" và để các agent chia nhau làm.
- Bộ nhớ qua nhiều phiên. Agent nhớ lại kinh nghiệm cũ thay vì bắt đầu từ trắng mỗi lần mở Claude Code. README cho biết phần truy xuất vector cục bộ có thể chạy mà không cần LLM, nhưng vẫn cần embedding và các module học được cấu hình.
- Hook tự động. Sau
init, hook tự định tuyến tác vụ và học từ mẫu làm việc thành công, bạn không phải gọi từng công cụ. - Máy chủ MCP. Codex hoặc các ứng dụng khách MCP khác cũng dùng được ruflo, không chỉ Claude Code.
- Bảng điều khiển (console). Theo dõi workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code, mở bằng lệnh
/ruflo. Bạn có thể xem log, tìm kiếm, phát lại và so sánh các lần chạy. - Claude điều khiển console, bạn đặt giới hạn. Trong Settings có mục Claude control với các mức
read,write,manage,fullvà chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiêu hay phá hủy luôn cần bạn xác nhận, kể cả ở chế độauto. - Hệ plugin. Có 48 plugin, chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps... Ví dụ
ruflo-swarmđể phối hợp agent,ruflo-testgenđể tìm chỗ thiếu test và sinh test,ruflo-cost-trackerđể theo dõi token và đặt ngân sách,ruflo-security-auditđể quét lỗ hổng. - 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. Đây là tính năng nâng cao, người mới chưa cần đến.
II.Cần chuẩn bị gì
Tư liệu nói rõ những điều sau:
- Node.js từ phiên bản 20.0.0 trở lên (theo
package.json). Lệnhnpxđi kèm Node. - Claude Code (hoặc Codex / một ứng dụng khách MCP) nếu bạn muốn dùng ruflo qua chúng.
- Nếu cài theo hướng chỉ dùng plugin của Claude Code, 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.
README phần đã cung cấp không nói gì về yêu cầu phần cứng, GPU hay hệ điều hành cụ thể, nên mình không khẳng định. Phần tài khoản và API key cho từng nhà cung cấp mô hình, bạn xem thêm trong tài liệu của repo.
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ách ly (sandbox). README khuyên đọc mã nguồn trước khi cài. Hãy làm theo, nhất là khi dùng trên máy có dữ liệu công việc quan trọng.
III.Cài đặt từng bước
README đưa ra ba đường chính. Cách đầu tiên (chạy init) là cách tác giả đề xuất và cho kết quả đầy đủ nhất. Mình hướng dẫn cách này trước.
- Kiểm tra NodeChắc chắn máy có Node từ 20 trở lên
- Mở terminal đúng chỗVà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 vào dự án
- Mở Claude CodeMở lại trong cùng thư mục để nó nhận cấu hình mới
- Giao việc thửDán một câu lệnh mẫu để xem swarm chạy
A.Kiểm tra Node
Mở terminal (PowerShell trên Windows, Terminal trên macOS) và xem phiên bản Node. Lệnh node --version là lệnh phổ thông, in ra số phiên bản. Cần từ 20 trở lên.
node --versionNếu máy chưa có Node hoặc cũ hơn 20, bạn cần cài hoặc nâng cấp Node trước.
B.Mở terminal đúng thư mục dự án
Đây là chỗ người mới hay vấp nhất: init ghi file vào thư mục hiện tại. Nếu bạn mở terminal ở sai chỗ (ví dụ thư mục Desktop), file sẽ nằm sai chỗ. Hãy cd vào đúng thư mục dự án trước.
cd duong-dan-toi-thu-muc-du-an-cua-banC.Chạy init
Đây là lệnh trong README:
npx ruflo@latest initinit thêm agent, hook, bộ nhớ và máy chủ MCP 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 và file như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings. Tức là nó sửa dự án của bạn, nên nếu dự án đang dùng Git thì nên commit trạng thái hiện tại trước để dễ so sánh.
Nếu muốn thiết lập 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
Claude Code nhận cấu hình mới ở lần khởi động kế tiếp. Hãy mở (hoặc khởi động lại) Claude Code trong cùng thư mục đã chạy init.
E.Cách khác: chỉ cài plugin trong Claude Code
Cách này không thêm file nào vào dự án. Bạn 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 trong 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, README cho lệnh:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý: README cảnh báo cách plugin chỉ cho "phiên bản nhẹ" (lệnh gạch chéo và một số skill). Bản đầy đủ gồm hook và daemon thì dùng npx ruflo@latest init.
F.Cách khác: Codex hoặc ứng dụng khách MCP
Trong phần cấu hình MCP của ứng dụng, đặt command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Hoặc chạy lệnh tương đương npx -y ruflo@latest mcp start.
G.Cách khác: chạy console trong terminal thường
Bảng điều khiển chạy độc lập, 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 README, bạn kiểm tra như sau:
- Sau
npx ruflo@latest init, trong thư mục dự án phải xuất hiện các mục như.claude/,.claude-flow/vàCLAUDE.md. - Mở lại Claude Code rồi gõ
/ruflo. Nếu console hiện ra, bạn đã có bảng điều khiển. - Nếu cài bằng plugin, gõ
/pluginvà xem các mod có nằm trong dòng "active mods" không. - Với console độc lập,
npx ruflo tuiphải mở giao diện trong terminal.
Phép thử thực tế nhất là cho Claude Code một việc thật (xem phần dưới) và xem nó có dùng swarm hay không.
V.Dùng vào việc thật
A.Rà soát một dự án có sẵn
Bối cảnh: bạn là lập trình viên mới nhận lại một dự án cũ, không biết chỗ nào dễ hỏng. Sau khi chạy init và mở lại Claude Code, bạn dán câu lệnh mẫu của chính 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: 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 đọc phần tóm tắt, rồi tự chạy test và xem lại thay đổi trước khi giữ.
Agent = Model + Harness. Mô hình lo viết, còn harness lo cho nó làm việc cho ra việc.
Ông T
B.Tạo "mission" và giữ quyền kiểm soát
Bối cảnh: bạn muốn thử bảng điều khiển nhưng chưa dám để Claude tự làm hết. README có sẵn kịch bản:
- Cài console (
ruflo-console@ruflo), mở/ruflo, vào Settings → Claude control, chọn write + ask. - Yêu cầu: “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 thao tác tạo.
- Kiểm tra Missions có mục tiêu đó và Overview có ghi lại hành động.
Lưu ý README nói rõ: tạo mission không có nghĩa tính năng đã được làm. Muốn dừng, bấm Take back control; các lệnh gọi sau đó của Claude sẽ bị từ chối cho đến khi bạn trả quyền lại.
C.Theo dõi chi phí khi để agent chạy lâu
Bối cảnh: bạn giao nhiều việc cho agent và lo tốn token. README liệt kê plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Cài theo cú pháp chung của README:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-cost-tracker@rufloSau đó mở console bằng /ruflo để xem token và chi phí cạnh Claude Code. README đã cung cấp không nêu chi tiết từng lệnh con của plugin này, bạn xem thêm trong tài liệu của plugin.
D.Sinh test cho phần code còn thiếu
Bối cảnh: nhóm nhỏ có code chạy được nhưng gần như chưa có test. Plugin ruflo-testgen được mô tả là "tìm test còn thiếu và tạo chúng tự động". Cài giống ví dụ trên (/plugin install ruflo-testgen@ruflo) rồi nhờ Claude Code tìm chỗ thiếu test trong module bạn chọn. Kết quả là các file test đề xuất; hãy tự chạy và đọc lại, đừng tin mù quáng.
VI.Lỗi hay gặp và cách xử lý
Gõ lệnh /plugin ... vào terminal thường nên báo lỗi. Các lệnh bắt đầu bằng dấu gạch chéo phải gõ bên trong Claude Code. Chỉ lệnh npx ... và claude plugin install ... mới gõ ở terminal.
Cài xong mà Claude Code không thấy gì. init cần Claude Code khởi động lại. Hãy đóng và mở lại trong đúng thư mục dự án. Với plugin, chạy /reload-plugins.
Lệnh plugin không chạy do Claude Code quá cũ. Cách plugin cần Claude Code 2.1.287 trở lên, lệnh claude plugin install cần 2.1.292 trở lên. Hãy cập nhật Claude Code.
Lỗi Node hoặc npx. package.json yêu cầu Node từ 20. Nếu node --version thấp hơn, nâng cấp Node rồi chạy lại.
Dự án bị thêm nhiều file lạ. init tạo .claude/, .claude-flow/, CLAUDE.md và các file khác. Nếu bạn chưa muốn thế, hãy thử trên một bản sao dự án, hoặc dùng cách chỉ cài plugin (không thêm file vào dự án).
VII.Có nên dùng không
Điểm mạnh: cài chỉ một lệnh; mã nguồn mở giấy phép MIT; repo vẫn được cập nhật trong vài tháng gần đây; hệ plugin rộng; có cơ chế giới hạn quyền (read/write/manage/full, ask/auto) và nút lấy lại quyền điều khiển.
Giới hạn: hệ thống 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. Một số phần là khái niệm; README tự nói sơ đồ kiến trúc "không phải vết thực thi thật", và các đoạn demo dùng dữ liệu mẫu, không chứng minh swarm đã hoàn thành việc thật. Mod chạy không sandbox với quyền tài khoản của bạn. Tư liệu cũng không nêu rõ chi phí token khi chạy nhiều agent, nên hãy theo dõi sát.
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 hoặc Codex trần là đủ. Nếu bạn muốn thử nhẹ, hãy cài từng plugin thay vì toàn bộ. Chỉ nên lên bản đầy đủ khi bạn thật sự cần agent phối hợp, bộ nhớ dài hạn và hook tự động.
Câu hỏi thường gặp
ruflo có miễn phí không?
Repo dùng giấy phép MIT, mã nguồn mở. Tuy nhiên bản thân ruflo chỉ là lớp điều phối; chi phí gọi mô hình AI (ví dụ qua Claude Code) tùy thuộc nhà cung cấp bạn dùng. README có plugin theo dõi token và ngân sách để bạn kiểm soát.
Cần cài gì trước khi dùng ruflo?
Cần Node.js từ phiên bản 20 trở lên và một ứng dụng như Claude Code hoặc Codex. Cách cài chỉ bằng plugin yêu cầu Claude Code từ 2.1.287 trở lên.
Cài ruflo bằng lệnh nào?
Trong thư mục dự án, chạy `npx ruflo@latest init`, rồi mở lại Claude Code trong cùng thư mục. Nếu muốn thiết lập có hướng dẫn, dùng `npx ruflo@latest init wizard`.
Ruflo có 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 ứng dụng khách MCP khác dùng được: đặt command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`.
Cài plugin và chạy init khác nhau thế nào?
Plugin không thêm file nào vào dự án, chỉ cho lệnh gạch chéo, một số skill và định nghĩa agent. `init` cho bộ đầy đủ gồm agent, lệnh, skill, máy chủ MCP, hook và daemon, đồng thời thêm các thư mục như `.claude/` và `.claude-flow/` vào dự án.
Ruflo có an toàn không, Claude có tự làm bậy được không?
Trong console, bạn chọn mức quyền (read, write, manage, full) và chế độ duyệt (ask hoặc auto). Mặc định hiện là read + ask, và các thao tác liên quan mạng, chi tiêu hay phá hủy luôn cần xác nhận. Tuy vậy các mod chạy với quyền tài khoản của bạn và không sandbox, nên cần đọc mã trước khi cài.
Có cần GPU hay chạy được trên Windows không?
Tư liệu đã cung cấp không nêu yêu cầu GPU hay danh sách hệ điều hành được hỗ trợ, nên chưa có thông tin chắc chắn. Lệnh cài chỉ dựa trên Node và npx; bạn nên thử trên dự án nhỏ trước.


