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 dùng nó để Claude Code làm việc có tổ chức hơn trên dự án thật. Cài khá dễ, 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 harness" (bộ khung điều phối agent) cho Claude Code và Codex. Hiểu đơn giản: mô hình AI thì viết code, còn Ruflo cung cấp phần xung quanh để nó làm việc được cả một dự án: công cụ, bộ nhớ, vòng lặp, các điều khiển và cách chia việc cho nhiều agent. 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.
Vấn đề nó giải quyết rất đời thường. Khi bạn giao cho Claude Code một việc lớn, mỗi phiên làm việc thường bắt đầu lại từ đầu, và bạn phải tự chia nhỏ việc. Ruflo thêm vào dự án các agent chuyên biệt, hook tự động định tuyến công việc, và bộ nhớ lưu lại kinh nghiệm giữa các phiên. Theo README, bạn vẫn dùng Claude Code như bình thường, còn Ruflo lo phần phối hợp phía sau.
Bạn nên đọc bài này nếu là lập trình viên (kể cả mới) đang dùng Claude Code hoặc Codex và muốn thử một hệ nhiều agent. Điểm đáng giá nhất là cách vào cửa rất nhẹ: một lệnh npx ruflo@latest init là đủ để bắt đầu. Bài này mình đi từ cài đặt, kiểm tra, đến vài tình huống dùng thật, và nói thẳng những chỗ README còn mơ hồ.
ruvnet/ruflo
Ruflo là lớp điều phối bao quanh Claude Code và Codex: thêm agent chuyên biệt, bộ nhớ qua các phiên, hook và máy chủ MCP chỉ bằng một lệnh npx.
I.Ruflo làm được gì
README giới thiệu khá nhiều thứ. Mình chọn ra những phần có ích nhất cho người mới.
A.Agent và swarm
Ruflo bổ sung hàng chục agent chuyên biệt (README ghi 98 agent ở đường cài CLI, ở phần khác ghi "100+"). Chúng có thể tự tổ chức thành "swarm", tức một nhóm agent chia việc cho nhau. Lợi ích thực tế: bạn đưa một yêu cầu lớn như "review cả repo", và việc được chia cho nhiều agent thay vì một agent làm tuần tự.
B.Bộ nhớ qua các phiên
Ruflo có bộ nhớ vector để lưu và truy xuất lại những gì agent đã học. README mô tả hệ thống ghi nhớ giữa các phiên và dùng kinh nghiệm cũ để định tuyến việc sau tốt hơn. README cũng ghi rõ đây là "sơ đồ khái niệm": phần tìm kiếm vector cục bộ chạy được không cần LLM, nhưng vẫn cần embedding và các module học đã cấu hình.
C.Hook tự động
Sau init, các hook sẽ tự định tuyến tác vụ và học từ những mẫu thành công. README nhấn mạnh bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Cứ dùng Claude Code như cũ.
D.Bảng điều khiển (console) ngay cạnh Claude Code
Plugin ruflo-console cho bạn một "buồng lái": theo dõi workflow, agent, mô hình, token và chi phí. Bạn mở nó bằng /ruflo trong Claude Code. Bạn cũng có thể cho Claude điều khiển console, nhưng với giới hạn do bạn đặt: read, write, manage hoặc full, kèm chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask.
E.Hệ plugin
README liệt kê 48 plugin (cộng 3 plugin bên ngoài) theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), học tập, chất lượng code (testgen, browser, docs), bảo mật (security-audit, aidefence), DevOps (cost-tracker, observability)... Bạn cài lẻ từng cái, không bắt buộc cài hết.
F.Liên kết nhiều máy và nhiều công cụ
Ruflo có federation (agent ở các máy khác nhau phối hợp an toàn), chạy được với Codex và các MCP client khác, và có tuỳ chọn cho Grok Build. Người mới chưa cần đến phần này, nhưng nên biết là có.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js 20.0.0 trở lên (package.json yêu cầu
>=20.0.0). Lệnhnpxđi kèm Node. - Claude Code nếu bạn muốn dùng cách chính. Nếu cài bằng plugin, cần Claude Code 2.1.287 trở lên; lệnh
claude plugin installtừ terminal cần 2.1.292 trở lên. - Hoặc Codex / một MCP client khác nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy
init.
README không nêu rõ yêu cầu hệ điều hành, phần cứng hay API key cụ thể cho việc cài. Riêng việc agent gọi tới nhà cung cấp mô hình nào thì phụ thuộc cấu hình của bạn, README chưa nói chi tiết trong phần mình có. Chi phí token phát sinh theo tài khoản Claude/Codex của bạn.
Mod và plugin chạy với quyền tài khoản của bạn và không bị cô lập (sandbox). README khuyên đọc code trước khi cài. Với tính năng "Claude control", đừng nâng mức quyền lên cao khi chưa cần.
III.Cài đặt từng bước
Có ba đường chính. Mình khuyên người mới đi đường đầu tiên.
- Mở terminal đúng chỗVào thư mục dự án của bạn
- Chạy initnpx ruflo@latest init
- Khởi động lại Claude CodeMở lại Claude Code trong cùng thư mục
- Thử lệnh /rufloMở bảng điều khiển để kiểm tra
A.Mở terminal trong 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ên bạn phải đứng đúng trong dự án cần dùng. Trên Windows, bạn có thể mở PowerShell rồi dùng cd. Ví dụ:
cd duong-dan/toi/du-an-cua-banB.Chạy lệnh init
Lệnh này thêm agent, hook, bộ nhớ và máy chủ MCP của Ruflo vào dự án. README nói đường cài CLI tạo ra các thư mục và file như .claude/, .claude-flow/, CLAUDE.md cùng các file hỗ trợ và cài đặt.
npx ruflo@latest initNếu muốn thiết lập theo kiểu hỏi đáp từng bước, README cho lệnh này:
npx ruflo@latest init wizardC.Mở lại Claude Code
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. Nếu bạn đang mở sẵn Claude Code, hãy đóng rồi mở lại.
D.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, nhưng chỉ cho bạn công cụ lõi, console và mod (nhẹ hơn đường init). Gõ 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
/rufloNếu dùng Claude Code 2.1.292 trở lên, bạn cũng có thể cài từ terminal thường:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloBảng so sánh trong README cho thấy hai đường khác nhau khá nhiều: plugin thì "zero file" trong dự án và không cài hook; còn npx ruflo init mới cho vòng lặp đầy đủ (98 agent, hơn 60 lệnh, 30 skill, máy chủ MCP, hook, daemon). README gọi đường init là phù hợp để dùng thật.
E.Cách khác: dùng với Codex hoặc MCP client khác
Không cần thiết lập dự án. Trong phần cấu hình MCP của công cụ, đặt command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]README cũng nói bạn có thể gõ trực tiếp npx -y ruflo@latest mcp start để khởi động máy chủ MCP.
F.Cách khác: chạy giao diện terminal
Console chạy được riêng, không cần Claude Code:
npx ruflo tuiThêm --plain để in ra một khung hình duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Theo README, có vài dấu hiệu để biết thành công:
- Sau
npx ruflo@latest init, trong thư mục dự án xuất hiện.claude/,.claude-flow/vàCLAUDE.md. - Mở lại Claude Code, gõ
/ruflothì bảng điều khiển hiện ra. - Nếu cài bằng plugin, mở
/pluginvà xem dòng "active mods" có tên các plugin bạn vừa cài. - Trong console, lệnh
/ruflo marketmở Plugin Catalog: danh sách plugin, mod và skill, có nút cài, bật, tắt, cập nhật (mỗi thao tác đều hỏi xác nhận).
Nếu bạn không thấy gì sau khi cài, hãy kiểm tra lại: đã khởi động lại Claude Code chưa, và có đang đứng đúng thư mục dự án không.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo ví dụ README đưa ra. Kết quả thực tế sẽ phụ thuộc dự án và mô hình bạn dùng.
A.Dev nhận repo lạ và muốn rà nhanh
Bạn vừa nhận một dự án chưa quen. Sau khi init và mở lại Claude Code, bạn 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.Yêu cầu này nhờ swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn nhận được một bản rà soát có tổ chức thay vì phải tự chia việc. Hãy đọc lại các test được sinh ra trước khi tin.
Agent = Model + Harness. Mô hình viết, còn bộ khung mới là thứ giúp nó làm việc thật.
Ông T
B.Người quản lý muốn nhìn tiến độ và chi phí
Bạn không code nhiều nhưng muốn biết agent đang làm gì và tốn bao nhiêu token. Bạn cài ruflo-console, mở /ruflo và xem workflow, agent, mô hình, token và chi phí cạnh Claude Code. README còn nói bạn có thể mở log và kết quả của từng 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. Plugin ruflo-cost-tracker cũng được mô tả là theo dõi token, đặt ngân sách và cảnh báo chi phí.
C.Để Claude tự thao tác console, nhưng có giới hạn
README có một bài thử từng bước:
- Cài console, mở
/ruflo, vào Settings → Claude control và chọn write + ask. - Nhập yêu cầu cụ thể: "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 đang chờ trong console.
- Kiểm tra mục Missions có mục tiêu mới và mục Overview ghi lại hành động.
- Bấm Take back control bất cứ lúc nào để dừng công cụ console của Claude.
Lưu ý README nhắc rõ: tạo mission không có nghĩa là tính năng đã được viết xong. Nó chỉ là bước đặt mục tiêu.
D.Dùng Ruflo với Codex hoặc công cụ MCP khác
Nếu bạn dùng Codex, bạn không phải chuyển sang Claude Code. Chỉ cần khai báo máy chủ MCP với npx -y ruflo@latest mcp start như phần cài đặt. Khi đó công cụ của bạn gọi được các công cụ MCP của Ruflo (ví dụ bộ nhớ, swarm). Tư liệu mình có chưa mô tả quy trình chi tiết cho Codex, nên bạn nên xem thêm hướng dẫn trong thư mục docs của repo.
VI.Lỗi hay gặp và cách xử lý
Một số lỗi dưới đây README nhắc trực tiếp, số khác là lỗi rất dễ gặp với loại công cụ này.
A.Lệnh npx báo lỗi hoặc không chạy
Nguyên nhân hay gặp là Node cũ. package.json yêu cầu Node 20 trở lên. Chạy node --version để kiểm tra, nâng cấp nếu thấp hơn rồi thử lại.
B.Gõ /plugin marketplace add mà không nhận lệnh
Cách plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 cho lệnh claude plugin install). Hãy cập nhật Claude Code. Sau khi cài plugin, nhớ chạy /reload-plugins.
C.Cài xong mà Claude Code không thấy gì
Hãy đóng hẳn Claude Code rồi mở lại trong đúng thư mục đã chạy init. Nếu bạn dùng đường plugin, kiểm tra /plugin xem plugin đã ở dòng active mods chưa.
D.Plugin 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ỉ nên cài từ một marketplace (của chính nó hoặc của ruflo), nếu bật cả hai thì mod và lệnh sẽ nạp hai lần. Hãy gỡ một bên.
E.Claude từ chối thao tác trong console
Đây là hành vi có chủ đích. Hành động vượt mức quyền bạn đặt sẽ bị từ chối, và các thao tác mạng, chi tiêu, phá huỷ vẫn cần xác nhận kể cả ở chế độ auto. Nếu cần, nâng mức quyền một cách có ý thức, hoặc tự làm thao tác đó.
F.Lo ngại về file được thêm vào dự án
Đường init thêm nhiều file vào dự án. Hãy chạy trên một nhánh hoặc dự án thử, và có commit sạch trước đó để dễ xem file nào mới sinh ra. Với Grok, README có cờ --dry-run để xem trước. Cờ này được ghi cho lệnh init --grok, nên đừng tự suy ra là mọi lệnh đều có.
VII.Có nên dùng không
Điểm mạnh. Vào cửa dễ (một lệnh), giấy phép MIT, được cập nhật gần đây, có cả đường cài nhẹ bằng plugin lẫn đường đầy đủ. Hệ sinh thái rộng: agent, bộ nhớ, console, bảo mật, theo dõi chi phí. README cũng trung thực ở vài chỗ, ví dụ ghi rõ bản demo dùng dữ liệu mẫu và chưa chứng minh việc swarm hoàn thành công việc thật hay việc nhớ lại bộ nhớ.
Giới hạn. Bề mặt rất lớn (hàng trăm công cụ MCP, hàng chục plugin), người mới dễ choáng. Đường init ghi nhiều file vào dự án. Mod không chạy trong sandbox, nên bạn phải tự đọc code. Tư liệu mình có chưa nói rõ hệ điều hành được hỗ trợ, và chưa có số liệu đo hiệu quả so với dùng Claude Code đơn thuần.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code viết vài đoạn code nhỏ, hoặc muốn một công cụ ít file và ít khái niệm, thì dùng Claude Code trơn là đủ. Nếu bạn tò mò mà chưa chắc, hãy thử đường plugin trước (không thêm file nào vào dự án), rồi mới lên đường init khi thấy hợp.
Câu hỏi thường gặp
Ruflo có miễn phí không?
Mã nguồn dùng giấy phép MIT nên bạn dùng và sửa được tự do. Tuy nhiên agent vẫn gọi tới mô hình AI qua tài khoản Claude hoặc Codex của bạn, nên chi phí token phát sinh theo gói của bạn. README có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.
Ruflo khác gì dùng Claude Code trơn?
Theo README, Ruflo là lớp bao quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ giữa các phiên, hook và máy chủ MCP. Bạn vẫn dùng Claude Code như bình thường, còn Ruflo phối hợp phía sau. Tư liệu chưa có số đo cụ thể về mức cải thiện.
Cần cài gì trước khi dùng?
Cần Node.js 20 trở lên và Claude Code (hoặc Codex/một MCP client). Nếu cài bằng plugin thì cần Claude Code 2.1.287 trở lên. README không nêu yêu cầu GPU cho đường cài cơ bản.
Cài nhanh nhất như thế nào?
Mở terminal trong thư mục dự án, chạy npx ruflo@latest init, rồi mở lại Claude Code. Sau đó giao một việc cụ thể, ví dụ nhờ swarm review repo và viết test cho module rủi ro nhất.
Dùng với Codex được không?
Được. README nói Codex và các MCP client khác hoạt động bằng cách trỏ tới lệnh npx với tham số -y, ruflo@latest, mcp, start. Bạn không cần thiết lập dự án.
Chạy trên Windows được không?
Tư liệu mình có chưa nêu rõ hệ điều hành được hỗ trợ. Công cụ chạy qua Node và npx nên bạn có thể thử, nhưng hãy xem thêm tài liệu trong repo để chắc chắn.
Cho Claude điều khiển console có an toàn không?
README mô tả cơ chế giới hạn: bạn chọn mức quyền read, write, manage hoặc full và chế độ duyệt ask hoặc auto, mặc định hiện là read + ask. Thao tác mạng, chi tiêu và phá huỷ luôn cần xác nhận, và bạn có thể bấm Take back control để dừng. Mod và plugin thì không bị sandbox, nên cần đọc code trước khi cài.


