Ruflo: điều phối nhóm agent AI 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, tức lớp công cụ bao quanh Claude Code và Codex để chạy nhiều agent phối hợp, có bộ nhớ và có kiểm soát. Bạn cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài không khó, nhưng repo rất lớn nên nên bắt đầu bằng một việc nhỏ.
Ruflo là một “agent harness”: lớp công cụ bao quanh Claude Code và Codex, giúp mô hình AI không chỉ trả lời một câu mà còn làm việc theo nhóm, nhớ lại việc cũ và chạy theo quy tắc bạn đặt. README tóm gọn bằng công thức: mô hình là người viết, còn harness là bàn làm việc gồm công cụ, bộ nhớ, vòng lặp và các chốt kiểm soát. Ruflo chính là phần bàn làm việc đó.
Bạn nên xem repo này nếu đang dùng Claude Code hoặc Codex hằng ngày và thấy một phiên chat đơn lẻ không đủ: việc dài, nhiều bước, cần chia cho nhiều “người” cùng làm, cần nhớ ngữ cảnh giữa các lần mở máy. Lập trình viên mới cũng dùng được, vì cách vào cuộc chỉ là một lệnh duy nhất rồi cứ dùng Claude Code như bình thường.
Điểm đáng giá nhất là độ “cắm vào là chạy”. Sau init, các agent, hook, bộ nhớ và MCP server được thêm vào dự án, và Claude Code tự nhận ở lần khởi động kế tiếp. Repo hiện có khoảng 81.588 sao và 9.608 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.
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ớ, hook và MCP server chỉ với một lệnh npx.
I.Ruflo làm được gì
README giới thiệu rất nhiều thứ, nên mình gom lại thành những ý bạn thực sự cảm nhận được khi dùng.
A.Chia việc cho nhóm agent (swarm)
Thay vì một AI làm tất cả, Ruflo cho nhiều agent chuyên biệt phối hợp thành một “bầy”. README nói có hơn 100 agent chuyên biệt. Lợi ích thực tế: một việc lớn như “rà soát cả repo, tìm chỗ rủi ro, viết test” được chia nhỏ thay vì dồn vào một cuộc hội thoại dài.
B.Bộ nhớ qua nhiều phiên
Ruflo có bộ nhớ tự học: ghi lại kinh nghiệm từ các việc đã làm và dùng lại để định tuyến việc sau. Nó cũng có tìm kiếm vector (RAG) cho bộ nhớ. Nhờ vậy bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code. README có ghi chú trung thực rằng phần truy xuất vector cục bộ chạy được mà không cần LLM, nhưng embedding và các module học vẫn cần được cấu hình.
C.Hook tự động định tuyến việc
Sau init, hệ thống hook chạy ngầm: tự chọn cách xử lý task, học từ các mẫu thành công và điều phối agent ở nền. README nhắn người mới rằng 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ư thường.
D.Bảng điều khiển (console) cạnh Claude Code
Đây là “buồng lái” để theo dõi workflow, agent, mô hình, token và chi phí. Bạn mở log của từng agent, tìm kiếm, xem lỗi, phát lại và so sánh các lần chạy. Có thêm Theme Studio để đổi giao diện.
E.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 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 bị từ chối; hành động liên quan mạng, chi tiêu hay phá huỷ vẫn phải xác nhận ngay cả khi để auto. Có nút Take back control để dừng ngay.
F.Hơn 40 plugin cắm thêm
README liệt kê 48 plugin (cộng 3 plugin bên ngoài), chia theo nhóm: điều phối (swarm, autopilot, workflow), bộ nhớ (agentdb, rag-memory), chất lượng code (testgen, browser, docs), bảo mật (security-audit, aidefence), vận hành (cost-tracker, observability) và nhiều nhóm khác. Bạn chỉ cài cái cần.
G.Liên kết giữa nhiều máy (federation)
Các agent trên máy khác nhau có thể trao đổi với nhau có bảo mật. Với người mới, đây là tính năng để sau; bạn không cần đụng tới khi mới bắt đầu.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js 20 trở lên.
package.jsoncủa repo yêu cầu>=20.0.0. Lệnhnpxđi kèm Node. - Claude Code nếu muốn dùng theo cách chính. Riêng đường cài bằng plugin thì README yêu cầu 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 ứng dụng hỗ trợ MCP, nếu bạn không dùng Claude Code.
- Một terminal mở ở đúng thư mục dự án của bạn.
README phần đã cung cấp không nói rõ về hệ điều hành, GPU hay API key bắt buộc. Vì Ruflo gọi các nhà cung cấp mô hình AI phía sau, bạn vẫn cần tài khoản dùng được Claude Code hoặc Codex như bình thường. Bạn nên xem thêm hướng dẫn trong thư mục docs/ của repo trước khi dùng cho việc quan trọng.
Các mod của Ruflo chạy với quyền tài khoản của bạn và không bị đặt trong sandbox. README khuyên đọc mã của mod trước khi cài. Với console, hãy để mức quyền thấp (read hoặc write kèm ask) cho đến khi bạn quen.
III.Cài đặt từng bước
- Mở terminalVào đúng thư mục dự án của bạn
- Chạy initMột lệnh npx để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude CodeKhởi động Claude Code trong cùng thư mục
- Giao việc thậtDán một câu lệnh mẫu để thử swarm
- Tuỳ chọnCài kiểu plugin, hoặc nối Codex qua MCP
A.Mở terminal ở thư mục dự án
Chỗ người mới hay vấp nhất: lệnh init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng thư mục dự án. Nếu chưa có thư mục nào, tạo thử một thư mục trống cho lần làm quen.
cd duong-dan-toi-du-an-cua-banB.Chạy lệnh init
Đây là lệnh chính trong README. Bạn chạy trong thư mục dự án:
npx ruflo@latest initnpx tải bản mới nhất của Ruflo và chạy luôn, không cần cài toàn cục. Theo README, init thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Ở bảng so sánh, cách này tạo ra các mục như .claude/, .claude-flow/ và CLAUDE.md trong thư mục làm việc.
Nếu muốn thiết lập có hỏi đáp từng bước, README có lệnh riêng:
npx ruflo@latest init wizardC.Mở Claude Code trong cùng thư mục
Claude Code chỉ nhận cấu hình mới ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn, hãy thoát rồi mở lại trong đúng thư mục đó.
D.Giao một việc thật
README gợi ý dán câ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 bằng tiếng Anh vì là prompt mẫu nguyên bản; bạn có thể giữ nguyên để thử trước.
E.Tuỳ chọn: cài bằng plugin Claude Code (không thêm file vào dự án)
Cách này README gọi là bản “lite”: không thêm file nào vào dự án, không cài hook. 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 thường, trên Claude Code 2.1.292 trở lên, README ghi thêm lệnh này:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloF.Tuỳ chọn: dùng với Codex hoặc ứng dụng MCP khác
Trong phần cấu hình MCP của ứng dụng, bạn khai báo lệnh (command) là npx và các tham số (arguments) là ["-y", "ruflo@latest", "mcp", "start"]. Tương đương dòng lệnh:
npx -y ruflo@latest mcp startTên ô nhập có thể khác nhau tuỳ ứng dụng, nhưng nội dung là như trên.
G.Tuỳ chọn: chỉ dùng giao diện terminal
Console chạy được độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain nếu muốn in ra đúng một khung hình để dùng trong script.
IV.Kiểm tra đã chạy được chưa
Với cách cài init:
- Xem thư mục dự án: theo README, bạn sẽ thấy các mục như
.claude/,.claude-flow/vàCLAUDE.md. - Khởi động lại Claude Code trong thư mục đó, rồi gõ
/ruflo. README ghi trình tự này để mở console.
Với cách cài plugin:
- Chạy
/reload-plugins, sau đó mở/plugin. Các mod bạn vừa cài phải xuất hiện trong dòng “active mods”. - Gõ
/ruflođể mở console. - Trong console, gõ
/ruflo marketđể mở Plugin Catalog, nơi liệt kê mọi plugin, mod và skill kèm nút cài, bật, tắt, cập nhật (mỗi thao tác đều hỏi lại trước).
Với cách chạy bằng terminal: npx ruflo tui phải hiện được giao diện console.
Nếu /ruflo không được nhận, xem phần lỗi hay gặp bên dưới.
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 ai nhớ module nào dễ hỏng. Sau khi init và mở lại Claude Code, bạn dán đúng prompt 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ả mong đợi theo mô tả của README: nhóm agent tìm module rủi ro nhất, viết test cho nó, rồi tóm tắt các thay đổi. Bạn xem lại và quyết định giữ hay bỏ, đừng coi đó là kết luận cuối.
Cứ dùng Claude Code như bình thường; phần điều phối để Ruflo lo ở nền.
Ông T
B.Quản lý dự án giao việc qua console, có duyệt từng bước
Bạn muốn thử cho Claude thao tác trên console mà vẫn nắm quyền. Làm theo trình tự của README:
- Cài console (
ruflo-console), mở/ruflo, chọn Settings → Claude control → write + ask. - 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 đang chờ.
- Kiểm tra mục Missions có mục tiêu mới, và Overview 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 viết xong. Nếu cần dừng, bấm Take back control.
C.Người phụ trách chi phí theo dõi token
Bạn lo hoá đơn dùng AI tăng lên. Trong danh sách plugin có ruflo-cost-tracker, mô tả là theo dõi lượng token, đặt ngân sách và cảnh báo chi phí. Cài từ marketplace đã thêm ở trên:
/plugin install ruflo-cost-tracker@rufloConsole cũng hiển thị token và chi phí ngay cạnh Claude Code, nên bạn có hai nơi để nhìn. README chưa nêu chi tiết cách đặt ngân sách trong phần mình có, nên hãy xem hướng dẫn của plugin sau khi cài.
D.Dev muốn thêm test cho code đang có
Nếu chưa muốn cài cả bộ, hãy thử từng plugin lẻ. ruflo-testgen được mô tả là tìm test còn thiếu và tự sinh ra. Thêm vào cùng ruflo-core:
/plugin install ruflo-testgen@rufloSau đó nhờ Claude chỉ ra phần code chưa có test và viết bổ sung. Đây là cách hợp với ai muốn thử mà không để lại file trong dự án.
VI.Lỗi hay gặp và cách xử lý
A.Node quá cũ hoặc chưa cài
Triệu chứng: npx báo không tìm thấy lệnh, hoặc lỗi lạ khi chạy. Repo yêu cầu Node 20 trở lên. 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 init.
B.Lệnh /plugin hoặc /ruflo không có tác dụng
Cách cài plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 trở lên cho lệnh claude plugin install ở terminal). Hãy cập nhật Claude Code. Sau khi cài xong, chạy /reload-plugins, hoặc thoát hẳn rồi mở lại Claude Code.
C.Chạy init nhưng Claude Code không thấy gì
Thường do bạn chạy init ở sai thư mục, hoặc chưa khởi động lại Claude Code. Kiểm tra thư mục có .claude/ và CLAUDE.md không, rồi mở Claude Code đúng thư mục đó.
D.Tên công cụ MCP khác nhau giữa hai cách cài
README cảnh báo: bản plugin đặt tên công cụ kiểu mcp__plugin_ruflo-core_ruflo__memory_store, còn bản CLI dùng tên ngắn như memory_store. Nếu bạn làm theo hướng dẫn của một cách nhưng đang cài cách kia, prompt gọi tên công cụ có thể không khớp. Muốn đầy đủ theo tài liệu, README khuyên dùng cách CLI (init).
E.Cài một plugin ngoài từ hai marketplace
Với các plugin bên ngoài như agentdb, agentic-flow, agentic-qe-fleet, README dặn chỉ cài từ một marketplace. Cài từ cả hai thì mod và lệnh bị nạp hai lần. Nếu đã lỡ, gỡ một bản đi.
F.Claude bị từ chối khi thao tác trong console
Đây thường không phải lỗi: hành động vượt mức quyền đã chọn sẽ bị từ chối, và các hành động nhạy cảm vẫn cần bạn xác nhận. Nâng quyền có chủ đích nếu thật sự cần, và nhớ rằng mức mặc định là read + ask.
VII.Có nên dùng không
Điểm mạnh. Cài đặt gọn bằng một lệnh. Có nhiều đường vào (init, plugin, MCP, terminal) cho các cách làm việc khác nhau. Có giấy phép MIT, cộng đồng lớn và repo vẫn hoạt động. Phần kiểm soát quyền của console được thiết kế khá cẩn thận: mặc định đọc và hỏi, có nút lấy lại quyền.
Giới hạn. Repo rất lớn, nhiều khái niệm (swarm, federation, ruOS, hàng chục plugin), nên người mới dễ choáng. README tự nói rõ một số bản demo dùng dữ liệu mẫu và không chứng minh việc swarm đã hoàn thành công việc thật, nên hãy tự kiểm chứng kết quả. Mod không bị sandbox. Chưa có thông tin về yêu cầu hệ điều hành hay chi phí cụ thể trong tư liệu mình có; chi phí phụ thuộc vào mô hình AI phía sau mà bạn dùng.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời vài câu hỏi hoặc sửa một file nhỏ, không cần thêm lớp điều phối. Nếu bạn muốn thử mà không muốn thêm file vào dự án, hãy chọn đường plugin lẻ. Lời khuyên của mình: bắt đầu trên một dự án thử, chạy đúng câu lệnh mẫu một lần, xem nó thay đổi gì, rồi mới quyết định có đưa vào việc chính hay không.
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 dùng tự do. Tuy nhiên Ruflo điều phối các mô hình AI như Claude hay Codex, và chi phí gọi các mô hình đó phụ thuộc vào tài khoản của bạn. Tư liệu không nêu bảng giá cụ thể.
Cài Ruflo cần những gì?
Cần Node.js 20 trở lên và một terminal mở ở thư mục dự án. Nếu cài theo kiểu plugin thì cần Claude Code 2.1.287 trở lên. Tư liệu không nói bắt buộc phải có GPU hay API key riêng.
Ruflo có dùng được với Codex hoặc công cụ ngoài Claude Code không?
Có. README nói Codex và các ứng dụng hỗ trợ MCP đều dùng được, bằng cách trỏ tới lệnh `npx -y ruflo@latest mcp start`. Repo cũng có lệnh `npx ruflo init --grok` cho Grok Build.
Khác gì giữa cài bằng init và cài bằng plugin?
`npx ruflo@latest init` cho vòng chạy đầy đủ (agent, lệnh, skill, MCP server, hook, daemon) và thêm file như `.claude/`, `CLAUDE.md` vào dự án. Cài plugin thì không thêm file vào dự án nhưng chỉ có lệnh gạch chéo, một số skill và định nghĩa agent, không có hook. README khuyên dùng `init` cho việc nghiêm túc.
Claude có tự ý làm bậy trong console được 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, mặc định là read kèm 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 bật auto, và bạn có thể bấm Take back control để dừng.
Chạy được trên Windows không?
Tư liệu mình có không nêu rõ danh sách hệ điều hành được hỗ trợ. Điều kiện được ghi rõ là Node 20 trở lên và dùng `npx`. Bạn nên xem README và thư mục docs của repo để chắc chắn.
Ruflo có phải là Claude Flow không?
Đúng, README cho biết Claude Flow nay đã đổi tên thành Ruflo, do Reuven Cohen (rUv) tạo ra. Gói npm của repo vẫn có tên claude-flow cùng với lệnh CLI.


