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 để chạy nhiều agent phối hợp, có bộ nhớ qua các phiên làm việc. Cài bằng một lệnh npx trong thư mục dự án, cần Node 20 trở lên. Người mới cài không khó, nhưng hệ thống rất rộng nên nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một "bộ khung" (harness) đặt quanh Claude Code và Codex. Nó thêm vào dự án của bạn các agent chuyên biệt, bộ nhớ, hook và một MCP server, để AI không chỉ trả lời từng câu mà làm việc theo nhóm và nhớ được việc đã làm. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, giấy phép MIT.
Vấn đề nó giải quyết khá quen thuộc: bạn dùng Claude Code cho việc lớn như rà soát cả repo, viết test, sửa lỗi, nhưng mỗi phiên đều bắt đầu lại từ đầu, và bạn phải tự chia việc. Ruflo chia việc giúp bạn bằng các "swarm" (nhóm agent), lưu kinh nghiệm vào bộ nhớ và định tuyến tác vụ tự động.
Ai nên dùng? Lập trình viên (kể cả người mới) đang dùng Claude Code hoặc Codex và muốn AI làm được việc dài hơi. Điểm đáng giá nhất là cài rất ngắn: một lệnh npx ruflo@latest init, rồi 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 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ụ ở phía sau.
ruvnet/ruflo
Ruflo là bộ khung bọc quanh Claude Code và Codex, thêm agent, bộ nhớ, hook và MCP server vào dự án chỉ với một lệnh npx.
I.Ruflo làm được gì
README mô tả Ruflo bằng công thức: Agent = Model + Harness. Model viết nội dung, còn harness cấp công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát. Ruflo là phần harness đó. Các ý chính:
- Nhiều agent chuyên biệt, phối hợp theo nhóm. README nói có 100+ agent; ở bảng so sánh cài đặt, bản CLI đầy đủ có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích: bạn giao một việc lớn, các agent tự chia nhau rà soát, viết test, tổng hợp.
- Bộ nhớ qua nhiều phiên. Agent nhớ được kinh nghiệm từ việc trước. README lưu ý phần học này 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 vẫn cần embedding và các module học đã cấu hình.
- Hooks tự động. Sau
init, hook định tuyến tác vụ và học từ các mẫu làm việc thành công, bạn không phải gọi tay. - MCP server. Claude Code, Codex hay client MCP khác đều gọi được công cụ của Ruflo.
- Bảng điều khiển (console) ngay cạnh Claude Code. Theo dõi workflow, agent, model, token và chi phí; xem lại log, tìm lỗi, so sánh các lần chạy. Mở bằng lệnh
/ruflo. - Cho Claude điều khiển console nhưng có giới hạn. Trong Settings, mục Claude control có các mức
read,write,manage,full, và chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận, kể cả khi đểauto. - 48 plugin cài riêng. Gồm swarm, bộ nhớ RAG, sinh test, quét bảo mật, theo dõi chi phí token, kiểm tra tài liệu và nhiều thứ khác. Bạn chọn cái cần dùng.
- Liên kết giữa các máy (federation). Agent trên máy khác có thể phối hợp, README nói là không làm lộ dữ liệu.
II.Cần chuẩn bị gì
Theo tư liệu, những thứ bạn cần:
- Node.js 20.0.0 trở lên. package.json yêu cầu đúng mức này.
- Claude Code hoặc Codex (hoặc client MCP khác) để dùng cùng Ruflo.
- Nếu cài theo đường plugin: Claude Code từ phiên bản 2.1.287 trở lên. Muốn dùng lệnh
claude plugin installtrong terminal thì cần từ 2.1.292. - Một thư mục dự án để chạy lệnh cài.
Tư liệu không nêu yêu cầu về GPU hay hệ điều hành cụ thể, và README đoạn mình đọc được cũng không nói về API key riêng của Ruflo. Việc dùng Claude Code hay Codex thì bạn cần tài khoản của chúng như bình thường.
Các mod của Ruflo chạy với quyền của tài khoản bạn và không có sandbox. README khuyên đọc code trước khi cài. Với console, hãy giữ mức quyền thấp (read + ask) cho đến khi bạn hiểu rõ nó làm gì.
III.Cài đặt từng bước
Có nhiều đường cài. Đường chính (đầy đủ nhất) là npx ruflo@latest init. Mình tóm tắt trước:
- Kiểm tra NodeCần Node 20 trở lên
- Mở terminal đúng chỗVào thư mục dự án của bạn
- Chạy initMột lệnh npx thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude CodeMở trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việcDùng câu lệnh mẫu của README
A.Kiểm tra Node và mở terminal đúng thư mục
Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux), đi tới thư mục dự án của bạn rồi kiểm tra Node. Lệnh node --version là lệnh phổ thông, bạn cần thấy số phiên bản từ 20 trở lên.
node --versionChỗ người mới hay vấp: lệnh 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 Downloads), file sẽ nằm sai dự án.
B.Chạy lệnh init (đường chính)
Đây là lệnh trong README, chạy trong thư mục dự án:
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 của README, nó tạo thư mục .claude/, .claude-flow/, file CLAUDE.md cùng một số file hỗ trợ và cấu hình. Vì vậy hãy chạy nó trong một dự án bạn đã commit hoặc sao lưu, để dễ xem Ruflo thêm gì.
Nếu muốn thiết lập có hỏi đáp, README ghi lệnh:
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 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 lúc chạy init, hãy đóng và mở lại.
D.Giao thử một việc thật
Gõ câu mẫu của README 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 bằng tiếng Anh, và bạn có thể giữ nguyên để đúng như tài liệu. Đây là một việc đủ nhỏ để xem nhóm agent làm việc ra sao.
E.Cách khác: chỉ cài plugin cho Claude Code
Đường này không thêm file nào vào dự án. README ghi: cài core tools, console và mods, cần Claude Code 2.1.287 trở lên. 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
/rufloTừ terminal, trên Claude Code 2.1.292 trở lên, README ghi thêm:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý: đường plugin chỉ cho lệnh gạch chéo, một số skill và định nghĩa agent. Nó không cài hook. Muốn chạy trọn vòng như tài liệu mô tả thì dùng đường init.
F.Cách khác: Codex hoặc client MCP khác
Với Codex hay client MCP, README bảo cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Dạng lệnh tương đương:
npx -y ruflo@latest mcp startG.Cách khác: chạy console trong terminal thường
Console cũng chạy độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain nếu bạn muốn in ra một khung duy nhất để dùng trong script.
IV.Kiểm tra đã chạy được chưa
Vài dấu hiệu theo tư liệu:
- Sau
init: trong thư mục dự án có.claude/,.claude-flow/vàCLAUDE.md. Mở lại Claude Code rồi gõ/ruflo, console sẽ hiện ra. - Sau khi cài plugin: gõ
/plugintrong Claude Code. README nói các mod đã cài sẽ xuất hiện ở dòng active mods. - Console độc lập:
npx ruflo tuimở giao diện terminal. Nếu thấy khung giao diện, nghĩa là gói chạy được. - Thử thật: giao câu lệnh mẫu về swarm ở trên và xem Claude có phối hợp nhiều agent không.
README không đưa ra một màn hình hay dòng thông báo cụ thể nào để coi là "cài xong". Nếu cần chi tiết hơn, xem phần hướng dẫn trong thư mục docs/ của repo.
V.Dùng vào việc thật
A.Lập trình viên rà soát một repo lạ
Bạn vừa nhận một dự án cũ, không biết đâu là chỗ dễ vỡ. Chạy npx ruflo@latest init trong thư mục dự án, mở Claude Code và dán câu mẫu: "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 theo README: module rủi ro nhất được chọn ra, có test viết cho nó, và bạn nhận bản tóm tắt thay đổi. Hãy đọc lại test trước khi commit, vì AI có thể viết sai.
Agent = Model + Harness. Model viết, còn harness cho nó công cụ, trí nhớ và giới hạn để làm việc thật.
Ông T
B.Theo dõi AI làm gì qua bảng điều khiển
Bạn muốn biết AI đã tốn bao nhiêu token và các agent đang làm gì. Cài console (/plugin install ruflo-console@ruflo), rồi gõ /ruflo. Console cho xem workflow, agent, model, token và chi phí cạnh Claude Code. Bạn mở log của từng lần chạy để tìm chỗ thất bại. Đây là cách giữ AI trong tầm nhìn khi giao việc dài.
C.Thử cho Claude tạo một "mission", có bạn duyệt
README có một bài thử an toàn. Trong console, vào Settings, mục Claude control, chọn write + ask. Rồi yêu cầu: "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. Kiểm tra mục Missions có mục tiêu và trang Overview ghi lại hành độ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.
D.Cài nhẹ từng plugin để thử
Bạn chưa muốn thêm file vào dự án, chỉ muốn thử vài lệnh. Dùng đường plugin (README gọi là Path A):
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@rufloBạn có lệnh gạch chéo và định nghĩa agent mà không đụng vào thư mục dự án. Nếu thấy hợp, chuyển sang init để có đủ bộ.
VI.Lỗi hay gặp và cách xử lý
A.Node quá cũ
Triệu chứng: npx báo lỗi khi chạy, hoặc gói không khởi động. Package yêu cầu Node 20 trở lên. Chạy node --version, nếu thấp hơn thì cập nhật Node rồi chạy lại lệnh.
B.Claude Code chưa nhận Ruflo
Sau init, bạn gõ /ruflo mà không thấy gì. Thường do Claude Code chưa được khởi động lại. Đóng hẳn, mở lại trong đúng thư mục đã chạy init. Với đường plugin, hãy chạy /reload-plugins.
C.Plugin không cài được vì phiên bản Claude Code thấp
Đường plugin cần Claude Code 2.1.287 trở lên; lệnh claude plugin install ở terminal cần 2.1.292 trở lên. Cập nhật Claude Code trước khi thử.
D.Cài plugin trùng từ hai nguồn
Với các plugin bên ngoài như agentic-qe-fleet, agentdb, agentic-flow, README cảnh báo chỉ cài từ một marketplace. Cài từ cả hai thì mod và lệnh sẽ nạp hai lần. Hãy gỡ một bên.
E.Gọi nhầm tên công cụ MCP
Bản plugin và bản CLI đặt tên công cụ khác nhau. Ví dụ plugin ruflo-core dùng tên dạng mcp__plugin_ruflo-core_ruflo__memory_store, không phải memory_store trần. Nếu agent gọi sai tên, kiểm tra bạn đang dùng đường cài nào.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh 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. Có console để nhìn thấy AI làm gì, có cơ chế phân quyền cho việc Claude điều khiển console, và hỗ trợ cả Claude Code lẫn Codex. Nếu bạn đã quen Claude Code và cần làm việc lớn hơn từng câu hỏi, đây là một lựa chọn đáng thử.
Giới hạn. Hệ thống rất rộng: hàng chục plugin, hàng trăm công cụ MCP. Người mới dễ choáng, nên bắt đầu từ init và một tác vụ nhỏ. README tự nói phần học là mô hình khái niệm, và các video demo dùng dữ liệu mẫu hoặc phát lại khung hình, chưa phải bằng chứng cho việc swarm hoàn thành công việc thật. Hãy tự kiểm chứng trên dự án của bạn. Các mod chạy không có sandbox. Tư liệu cũng chưa nói rõ chi phí token khi chạy nhiều agent, nên hãy theo dõi bằng console hoặc plugin theo dõi chi phí.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời vài câu hoặc sửa file nhỏ, bản thường đã đủ. Nếu bạn không muốn bất kỳ file lạ nào trong dự án, dùng đường plugin nhẹ hoặc chỉ gắn MCP server thay vì init. Nếu bạn không phải dân lập trình và chưa dùng Claude Code lần nào, hãy làm quen công cụ gốc trước rồi mới thêm Ruflo.
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 hoặc Codex, và chi phí của các dịch vụ đó là riêng. Tư liệu không nói rõ chi phí token khi chạy nhiều agent, nhưng có plugin theo dõi chi phí và console hiển thị token.
Cài Ruflo cần phiên bản Node nào?
package.json yêu cầu Node 20.0.0 trở lên. Bạn kiểm tra bằng lệnh node --version trước khi chạy npx ruflo@latest init.
Ruflo khác gì Claude Code thường?
Claude Code là công cụ chính để AI viết và sửa code. Ruflo là lớp bao quanh, thêm agent chuyên biệt, swarm, bộ nhớ qua phiên, hook và MCP server. Bạn vẫn làm việc trong Claude Code, Ruflo lo phần phối hợp phía sau.
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 bằng cách cấu hình command là npx với tham số -y, ruflo@latest, mcp, start. Ngoài ra có lệnh npx ruflo init --grok cho Grok Build.
Có chạy được trên Windows không, có cần GPU không?
Tư liệu mình có không nêu hệ điều hành hay yêu cầu GPU cụ thể. Điều kiện duy nhất được ghi rõ là Node 20 trở lên. Nếu cần chắc chắn, hãy xem thêm trong thư mục docs/ của repo.
Cài Ruflo có làm thay đổi dự án của tôi không?
Nếu dùng npx ruflo@latest init thì có: nó thêm .claude/, .claude-flow/, CLAUDE.md và một số file hỗ trợ. Nếu dùng đường plugin cho Claude Code thì README nói không thêm file nào vào dự án.
Có an toàn không khi cho Claude điều khiển console?
README mô tả bốn mức quyền (read, write, manage, full) và hai chế độ duyệt (ask, auto). Mặc định hiện là read + ask. Hành động liên quan mạng, chi tiêu hay phá huỷ vẫn cần xác nhận, và bạn bấm Take back control để dừng. Riêng các mod thì chạy với quyền tài khoản của bạn và không có sandbox, nên cần đọc code trước khi cài.


