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, thêm agent chuyên biệt, swarm, bộ nhớ và hook. Chỉ cần chạy npx ruflo@latest init trong thư mục dự án, rồi mở lại Claude Code. Cài không khó, nhưng cần Node 20 trở lên và nên hiểu nó sẽ thêm file vào dự án.
ruflo là một agent harness, tức bộ khung bao quanh Claude Code và Codex để biến một trợ lý AI đơn lẻ thành một nhóm agent biết phối hợp, nhớ việc cũ và có công cụ điều khiển. Trước đây dự án tên là Claude Flow, do Reuven Cohen (rUv) xây dựng. Giấy phép MIT, viết chủ yếu bằng TypeScript, hiện có khoảng 81.600 sao và khoảng 9.600 fork trên GitHub.
Vấn đề nó giải quyết khá quen thuộc. Claude Code tự nó đã giỏi viết code. Nhưng khi việc lớn dần (review cả repo, viết test, ghi nhớ quyết định từ tuần trước), một phiên chat đơn lẻ dễ quên và khó kiểm soát. README mô tả công thức: Agent = Model + Harness. Model viết, còn harness lo công cụ, bộ nhớ, vòng lặp và giới hạn an toàn. ruflo là phần harness đó.
Bạn nên thử nếu đang dùng Claude Code hoặc Codex hằng ngày và muốn giao việc nhiều bước hơn. Điểm đáng giá nhất là cách cài rất gọn: một lệnh npx ruflo@latest init, sau đó bạn cứ dùng Claude Code như bình thường. README nói hệ thống hook sẽ tự định tuyến việc và phối hợp agent ở phía sau.
ruvnet/ruflo
ruflo là bộ khung giúp 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.
I.ruflo làm được gì
README liệt kê rất nhiều thứ. Mình gom lại những ý có lợi thực tế nhất.
A.Nhóm agent phối hợp (swarm)
Thay vì một AI làm tất cả, ruflo cho nhiều agent tự tổ chức thành nhóm. README ghi sau khi init có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích: một yêu cầu như review repo có thể chia cho nhiều agent, mỗi agent lo một phần.
B.Bộ nhớ qua nhiều phiên
ruflo có bộ nhớ dạng vector để agent nhớ việc đã làm giữa các phiên. Các plugin liên quan là ruflo-agentdb, ruflo-rag-memory và ruflo-rvf (lưu và khôi phục bộ nhớ). Với bạn, nghĩa là bớt phải giải thích lại bối cảnh dự án mỗi lần mở máy.
C.Học từ việc đã làm
README nói agent học từ các mẫu thành công và đưa kinh nghiệm đó trở lại bước định tuyến. Cũng theo README, phần truy xuất vector và cập nhật tương phản ở máy 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.
D.Bảng điều khiển ruflo-console
Đây là phần dễ thấy nhất. Nó là bảng điều khiển chạy cạnh Claude Code, để theo dõi workflow, agent, model, token và chi phí. Bạn mở xem log từng agent, tìm kiếm, phát lại và so sánh các lần chạy. Mở bằng lệnh /ruflo trong Claude Code.
E.Cho Claude điều khiển, 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, và chọn cách duyệt ask hoặc auto. Mặc định hiện là read + ask. Theo README, các hành động vượt quyền sẽ bị từ chối, còn hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần xác nhận kể cả ở chế độ auto.
F.Hệ plugin lớn
README ghi 48 plugin (cộng thêm 3 plugin bên ngoài). Ví dụ: ruflo-swarm (phối hợp agent), ruflo-testgen (tìm test còn thiếu và sinh test), ruflo-security-audit (quét lỗ hổng), ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí), ruflo-docs (tạo và duy trì tài liệu). Bạn không cần dùng hết, chọn cái nào cần.
G.Hỗ trợ Codex và client MCP khác
Ngoài Claude Code, Codex và các client MCP khác cũng dùng được bằng cách trỏ tới npx -y ruflo@latest mcp start. README còn nhắc tới Grok Build qua npx ruflo init --grok.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js từ phiên bản 20.0.0 trở lên. File package.json của repo yêu cầu đúng như vậy.
- Claude Code (hoặc Codex / một client MCP khác). Nếu đi đường plugin thì cần Claude Code 2.1.287 trở lên. Lệnh cài plugin từ terminal cần Claude Code 2.1.292 trở lên.
- Một thư mục dự án để chạy lệnh init.
README không nêu yêu cầu hệ điều hành cụ thể, không nêu yêu cầu GPU, và phần README mình có không nói gì về API key riêng cho ruflo. Bạn dùng Claude Code hay Codex thì cần tài khoản của các công cụ đó như bình thường. Nếu bạn muốn biết chắc về key hay phần cứng cho từng plugin, hãy đọc README từng plugin trong repo.
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. Hãy giữ nguyên mức Claude control mặc định (read + ask) cho tới khi bạn quen.
III.Cài đặt từng bước
README có ba đường: cài bằng npx vào dự án (đầy đủ nhất), cài chỉ plugin cho Claude Code (không thêm file vào dự án), và dùng như MCP server cho Codex. Mình hướng dẫn đường đầu tiên.
- Kiểm tra NodeChắc chắn máy có Node 20 trở lên
- Mở terminal trong dự ánVào đúng thư mục dự án của bạn
- Chạy initnpx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude CodeMở Claude Code ở cùng thư mục để nó nhận cấu hình mới
- Giao việc đầu tiênGõ một yêu cầu thật, ví dụ review repo
A.Kiểm tra Node
ruflo cần Node từ 20 trở lên. Gõ lệnh dưới đây để xem phiên bản. Nếu số đầu nhỏ hơn 20, bạn cần cập nhật Node trước.
node --versionB.Mở terminal trong thư mục dự án
Đây là chỗ người mới hay vấp. 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, không phải thư mục Home hay Desktop. Trên Windows, bạn có thể mở PowerShell rồi dùng cd tới thư mục dự án.
cd đường-dẫn-tới-dự-án-của-bạnC.Chạy init
README ghi lệnh này chạy trong thư mục dự án. Theo README, init thêm agent, hook, bộ nhớ và MCP server của ruflo vào dự án. Bảng so sánh trong README nói bạn sẽ thấy các thư mục và file như .claude/, .claude-flow/, CLAUDE.md cùng một số file helper và settings.
npx ruflo@latest initNếu muốn cài theo kiểu hỏi đáp từng bước cho dự án, README có lệnh riêng:
npx ruflo@latest init wizardD.Mở lại Claude Code
Mở Claude Code ở 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 kế tiếp. Nếu bạn đang mở sẵn Claude Code lúc chạy init, hãy thoát ra và mở lại.
E.Giao việc đầu tiên
README đưa sẵn một yêu cầu mẫu. Bạn gõ 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.F.Đường khác: chỉ cài plugin cho Claude Code
Cách này không thêm file nào vào dự án. Cần Claude Code 2.1.287 trở lên. Các lệnh dưới đây gõ 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
/rufloNếu dùng Claude Code 2.1.292 trở lên, bạn cũng có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý theo README: bản plugin chỉ cho bạn lệnh slash, vài skill và định nghĩa agent. Hook không được cài, và MCP server chỉ có khi cài ruflo-core. Muốn có vòng lặp đầy đủ (agent, lệnh, skill, MCP, hook, daemon) thì dùng npx ruflo init.
G.Đường khác: Codex hoặc client MCP khác
Không cần setup dự án. Bạn cấu hình command là npx và arguments là mảng dưới đây (cách điền cụ thể tuỳ client bạn dùng):
["-y", "ruflo@latest", "mcp", "start"]IV.Kiểm tra đã chạy được chưa
Theo README, có vài dấu hiệu để biết cài 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õ
/ruflođể mở bảng điều khiển (README ghi quy trình là init, khởi động lại Claude Code, rồi/ruflo). - Nếu cài bằng plugin, gõ
/pluginvà xem các mod có xuất hiện trong dòng active mods hay không. - Trong console, lệnh
/ruflo marketmở Plugin Catalog: danh sách mọi plugin, mod và skill, kèm nút cài, bật, tắt và cập nhật (mỗi thao tác đều hỏi lại bạn).
Ngoài ra, bảng điều khiển cò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.
V.Dùng vào việc thật
Bám theo những gì README mô tả, đây là vài tình huống bạn có thể thử.
A.Lập trình viên: review nhanh một repo lạ
Bạn vừa nhận một dự án cũ từ đồng nghiệp, chưa biết chỗ nào nguy hiểm. Sau khi chạy init và mở lại Claude Code, bạn gõ đúng yêu cầu mẫu của README: dùng swarm để review repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Kết quả mong đợi là Claude điều phối agent, đề xuất module rủi ro, thêm test và báo lại thay đổi. Bạn vẫn nên đọc lại diff trước khi giữ.
Bạn tiếp tục viết code như bình thường, còn việc phối hợp agent cứ để bộ khung lo.
Ông T
B.Người mới: làm quen bảng điều khiển bằng việc nhỏ, an toàn
Nếu chưa dám giao việc lớn, hãy làm theo bài thử trong README. Mở /ruflo, vào Settings → Claude control và chọn mức write + ask. Rồi nhắn Claude:
Create a mission to add a dark mode toggle. Show me the mission and its status.Claude sẽ mở mục Missions và đặt mục tiêu, bạn xác nhận hành động tạo. Sau đó kiểm tra mục Missions có mục tiêu mới chưa và Overview có ghi lại hành động không. README nhấn mạnh: tạo mission không có nghĩa tính năng đã được làm xong. Bạn có thể bấm Take back control bất cứ lúc nào để Claude không dùng được các công cụ của console nữa.
C.Người dùng Codex: dùng ruflo như MCP server
Bạn không dùng Claude Code mà dùng Codex. Bạn không cần init cho dự án, chỉ cần khai báo MCP server với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Kết quả: Codex có thêm công cụ ruflo. Chi tiết cách điền vào từng client bạn xem tài liệu của client đó, vì README không viết hộ.
D.Người quan tâm chi phí: theo dõi token
Nếu bạn lo agent chạy tốn token, README có plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Cú pháp cài giống các plugin khác: /plugin marketplace add ruvnet/ruflo trước, rồi /plugin install ruflo-cost-tracker@ruflo. Bảng điều khiển console cũng hiển thị token và chi phí cạnh Claude Code. Phần README mình có chưa mô tả chi tiết cách đặt ngân sách, nên hãy xem hướng dẫn của plugin trong thư mục plugins/ của repo.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh npx báo lỗi hoặc không chạy
Nguyên nhân hay gặp là Node cũ hơn 20. Chạy node --version, cập nhật Node lên 20 trở lên rồi chạy lại npx ruflo@latest init.
B.Chạy init xong mà Claude Code không thấy gì
README nói Claude Code chỉ nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn và mở lại Claude Code đúng thư mục bạn đã chạy init. Kiểm tra thư mục đó có .claude/ và CLAUDE.md chưa.
C.Lệnh /plugin install không có hoặc không chạy
Đường plugin cần Claude Code 2.1.287 trở lên (lệnh claude plugin install từ terminal cần 2.1.292 trở lên). Hãy cập nhật Claude Code. Sau khi cài, gõ /reload-plugins rồi /plugin để xem plugin đã hiện chưa.
D.Không thấy MCP tool hoặc tên tool khác với tài liệu
Theo README, plugin ruflo-core đăng ký MCP server riêng và các tool có tên dạng mcp__plugin_ruflo-core_ruflo__*, khác với tên ngắn như memory_store hay swarm_init của đường CLI. Nếu bạn cần đúng tên tool trong tài liệu, hãy dùng đường npx ruflo init.
E.Plugin bên ngoài bị nạp hai lần
Với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow, README dặn cài từ một marketplace duy nhất. Nếu bật từ cả hai nơi, mod và lệnh của chúng sẽ nạp hai lần. Hãy gỡ một bản.
F.Claude từ chối thao tác trong console
Đây thường không phải lỗi mà là giới hạn bạn đã đặt. Hành động vượt mức quyền bị từ chối. Nếu cần, nâng mức quyền trong Settings → Claude control, nhưng nâng từng nấc và giữ chế độ ask.
VII.Có nên dùng không
Điểm mạnh. Cài rất nhanh, một lệnh. Phạm vi rộng: agent, bộ nhớ, console theo dõi, hệ plugin lớn. Giấy phép MIT, repo còn được cập nhật trong vài tháng gần đây. Cơ chế giới hạn quyền cho Claude (mức read/write/manage/full, ask/auto) cho cảm giác an tâm hơn khi để AI tự chạy.
Giới hạn. Dự án rất đồ sộ (406 MCP tool, 61 lệnh CLI, 48 plugin theo README), nên dễ bị choáng. README cũng thừa nhận bạn không cần học hết, cứ dùng Claude Code như thường sau init. Lệnh init thêm khá nhiều file vào dự án, nên với dự án quan trọng hãy dùng nhánh git riêng khi thử. README tự nói một số 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 bộ nhớ gợi lại đúng. Hãy tự thử trên việc nhỏ trước khi tin.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời và sửa vài file, dùng Claude Code trơn là đủ. Nếu chỉ muốn thử một tính năng, cài đúng một plugin theo đường lite sẽ nhẹ hơn nhiều. Còn nếu bạn không lập trình và không dùng Claude Code hay Codex, repo này chưa phải công cụ dành cho bạn.
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, nên chi phí của các dịch vụ đó vẫn theo tài khoản của bạn. README có plugin ruflo-cost-tracker để theo dõi token và chi phí.
Cài ruflo cần gì?
Cần Node.js từ phiên bản 20 trở lên và Claude Code (hoặc Codex, client MCP khác). Đường cài plugin cần Claude Code 2.1.287 trở lên. Phần README mình có không nêu yêu cầu GPU.
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 ở cùng thư mục. Nếu không muốn thêm file vào dự án, bạn có thể cài plugin bằng /plugin marketplace add ruvnet/ruflo rồi /plugin install ruflo-core@ruflo.
ruflo có dùng được với Codex 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 arguments ["-y", "ruflo@latest", "mcp", "start"]. Cách điền cụ thể tuỳ từng client.
Chạy được trên Windows không?
Phần README mình có không nêu rõ hệ điều hành được hỗ trợ. Lệnh cài chỉ cần Node và npx nên về nguyên tắc chạy được ở nơi có Node 20 trở lên, nhưng chưa có thông tin chính thức. Bạn nên thử trước trên một dự án nhỏ.
Init có làm hỏng dự án của tôi không?
Theo README, init thêm các thư mục và file như .claude/, .claude-flow/, CLAUDE.md và file helper, settings vào dự án. Hãy dùng nhánh git riêng khi thử để dễ xem lại và hoàn tác. Nếu không muốn thêm file nào, dùng đường plugin.
Claude có tự ý làm việc nguy hiểm không?
README nói mặc định là read + ask, và bạn tự chọn nâng quyền. Các hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần xác nhận kể cả ở chế độ auto. Bạn có thể 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.


