ruflo: điều phối nhiều 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 "harness" bao quanh Claude Code và Codex. Nó thêm đội agent, bộ nhớ dùng lại giữa các phiên, hook và MCP server để AI làm việc có tổ chức hơn. Cài khá đơn giản: cần Node từ bản 20 trở lên và chạy một lệnh `npx ruflo@latest init` trong thư mục dự án.
Ruflo là một bộ khung (agent harness) chạy bao quanh Claude Code và Codex. Nó thêm cho AI các "công cụ làm việc": nhiều agent chuyên biệt, bộ nhớ giữ lại giữa các phiên, hook tự động và một MCP server. Nhờ vậy AI không chỉ trả lời từng câu hỏi lẻ mà làm việc theo nhóm, có kế hoạch. 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.
Vấn đề nó giải quyết khá quen thuộc. Bạn dùng Claude Code, giao một việc lớn, và AI dễ quên bối cảnh, làm từng bước rời rạc, mỗi phiên lại bắt đầu từ đầu. README của Ruflo mô tả bằng một công thức: Agent = Model + Harness. Model là phần viết code. Harness là phần cấp công cụ, bộ nhớ, vòng lặp và giới hạn để model làm được việc thật. Ruflo đóng vai harness đó.
Ai nên dùng? Lập trình viên đã quen Claude Code hoặc Codex và muốn giao những việc nhiều bước như rà soát repo, viết test, ghi lại thay đổi. Người mới cũng thử được vì README nhấn mạnh: sau init bạn cứ dùng Claude Code bình thường, phần phối hợp agent chạy ngầm. Điểm đáng giá nhất là cài chỉ bằng một lệnh, kèm một bảng điều khiển (console) để xem agent đang làm gì và tốn bao nhiêu token.
ruvnet/ruflo
Ruflo là bộ khung bao quanh Claude Code và Codex, thêm đội agent, bộ nhớ, hook và MCP server vào dự án chỉ bằng một lệnh npx.
I.Ruflo làm được gì
Theo README, Ruflo gom nhiều thứ vào một chỗ. Mình tóm lại theo lợi ích bạn nhận được.
- Đội agent làm việc cùng nhau (swarm). Thay vì một AI làm tất cả, nhiều agent chia việc và phối hợp. README ghi bản cài đầy đủ có 98 agent chuyên biệt. Bạn giao một việc lớn, các agent tự chia nhau.
- Bộ nhớ qua các phiên. Agent nhớ những gì đã làm và dùng lại kinh nghiệm từ các việc thành công trước đó. 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ó nói thêm rằng phần học này cần embedding và các module học được cấu hình, không phải chạy hoàn toàn không cần gì.
- Hook tự định tuyến. Sau khi cài, hook tự chọn cách xử lý cho từng việc và ghi nhận mẫu làm việc hiệu quả. README nói bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI.
- Bảng điều khiển cạnh Claude Code. Console cho bạn theo dõi workflow, agent, model, token và chi phí. Bạn mở log của từng lần chạy, tìm kiếm, xem lại lỗi, so sánh các lần chạy. Mở bằng lệnh
/ruflo. - Cho Claude lái console trong giới hạn bạn đặt. Trong Settings → Claude control bạn chọn mức quyền
read,write,managehoặcfull, và chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask, tức Claude chỉ được xem và phải hỏi bạn. Các 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ả ở chế độauto. - Hệ plugin lớn. README liệt kê 48 plugin (cộng 3 plugin bên ngoài) theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps. Ví dụ
ruflo-testgentìm chỗ thiếu test và tạo test,ruflo-cost-trackertheo dõi token và đặt ngân sách,ruflo-security-auditquét lỗ hổng. - Liên kết nhiều máy (federation). Agent trên các máy khác nhau nói chuyện được với nhau. Đây là phần nâng cao, người mới chưa cần.
II.Cần chuẩn bị gì
Chỉ liệt kê những gì tư liệu nói:
- Node.js bản 20.0.0 trở lên. Đây là yêu cầu ghi trong package.json của repo.
- Claude Code nếu bạn đi đường cài plugin. Cần Claude Code bản 2.1.287 trở lên. Muốn cài plugin từ terminal thì cần bản 2.1.292 trở lên.
- Hoặc Codex / một MCP client khác. README nói các client này dùng được bằng cách trỏ tới lệnh khởi động MCP server của Ruflo.
- Giấy phép MIT, ngôn ngữ chính là TypeScript.
Tư liệu không nói rõ về hệ điều hành, yêu cầu phần cứng hay API key riêng của Ruflo. Bạn vẫn cần tài khoản và quyền dùng Claude Code hoặc Codex như bình thường. Nếu muốn biết chi tiết hơn, xem README.md và thư mục docs trong repo.
Một số mod chạy bằng đúng 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 Claude control, hãy giữ mức mặc định read + ask cho đến khi bạn hiểu rõ nó làm gì.
III.Cài đặt từng bước
README có hai đường cài với phạm vi rất khác nhau. Đường 1 (CLI, npx ruflo@latest init) cho đầy đủ: 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon. Nó thêm file vào dự án: .claude/, .claude-flow/, CLAUDE.md, các file hỗ trợ và settings. Đường 2 (plugin Claude Code) nhẹ hơn: không thêm file nào vào dự án, chỉ có lệnh slash, vài skill và định nghĩa agent. README ghi đường CLI hợp với dùng thật, nên mình hướng dẫn đường này trước.
- Vào thư mục dự ánMở terminal ngay trong thư mục dự án bạn muốn dùng
- Chạy initGõ npx ruflo@latest init để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao việc thửĐưa cho Claude Code một việc thật có nhắc tới swarm
- Mở bảng điều khiểnGõ /ruflo để xem agent, token và chi phí
A.Mở terminal đúng thư mục
Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. init ghi file vào nơi bạn đang đứng, nên hãy cd vào đúng dự án trước. Ví dụ với một dự án đã có trên máy:
cd ten-thu-muc-du-anThay ten-thu-muc-du-an bằng thư mục thật của bạn. Nếu bạn muốn lấy mã nguồn Ruflo về xem, dùng git clone https://github.com/ruvnet/ruflo.git, nhưng để dùng thì không cần, npx tự tải về.
B.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initnpx tải và chạy Ruflo bản mới nhất mà không cần cài toàn cục. Lệnh init thêm agent, hook, bộ nhớ và MCP server vào dự án. Nếu máy báo lỗi về Node, hãy kiểm tra bạn đã có Node 20 trở lên.
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 wizardC.Mở lại Claude Code và giao việc thử
Mở Claude Code trong cùng thư mục. Claude Code sẽ nhận cấu hình của Ruflo ở lần khởi động tiếp theo, nên nếu đang mở sẵn, hãy đóng rồi mở lại. Sau đó thử một việc thật, 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.Bạn có thể viết bằng tiếng Việt, nhưng mình giữ nguyên câu gốc của README để chắc chắn đúng cách gọi "ruflo swarm".
D.Cách khác: chỉ cài plugin trong Claude Code
Nếu bạn không muốn thêm file vào dự án, hãy gõ lần lượt các lệnh sau bên trong Claude Code (không phải 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
/rufloCác lệnh này thêm kho plugin, cài lõi, bảng điều khiển và mod, nạp lại plugin rồi mở console. Nếu dùng Claude Code 2.1.292 trở lên, bạn cũng cài được từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloCòn muốn thêm plugin swarm hay bộ nhớ RAG, README có các lệnh /plugin install ruflo-swarm@ruflo và /plugin install ruflo-rag-memory@ruflo.
E.Cách khác: Codex hoặc MCP client khác
Không cần cài vào dự án. Trong phần cấu hình MCP của client, đặt command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]README còn nhắc lệnh này ở dạng viết liền: npx -y ruflo@latest mcp start. Cách điền cụ thể tuỳ từng client, bạn xem tài liệu của client đó.
F.Chạy bảng điều khiển trong terminal thường
Console chạy độc lập, 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ác dấu hiệu cài thành công như sau:
- Sau
npx ruflo@latest init, trong thư mục dự án có thêm.claude/,.claude-flow/vàCLAUDE.md. Bạn mở thư mục ra xem là biết. - Mở lại Claude Code rồi gõ
/ruflo. Nếu bảng điều khiển hiện ra thì Ruflo đã được nhận. - Nếu cài bằng plugin, gõ
/pluginđể xemruflo-consolevàruflo-modscó nằm trong dòng mod đang hoạt động không. - Thử giao câu lệnh mẫu ở trên và xem Claude Code có nhắc tới swarm, agent hay không.
- Nếu dùng Codex, kiểm tra client đã liệt kê được các công cụ của MCP server
ruflo. README chưa mô tả màn hình cụ thể ở bước này.
Tư liệu không nêu chuỗi thông báo thành công chính xác cho từng lệnh. Nếu bạn không chắc, xem hướng dẫn "First useful task" trong docs của repo.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo những khả năng README mô tả. Kết quả thực tế sẽ tuỳ dự án và model bạn dùng.
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. Hãy chạy npx ruflo@latest init trong thư mục dự án, mở lại Claude Code và dùng đúng câu lệnh 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: Claude Code điều phối các 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 nên đọc lại test và phần thay đổi trước khi chấp nhận.
B.Trưởng nhóm tập làm quen với bảng điều khiển
Bạn muốn thấy AI đang làm gì thay vì chờ mù. README có kịch bản thử an toàn: vào /ruflo, chọn Settings → Claude control → write + ask, rồi 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. Sau đó kiểm tra Missions có mục tiêu mới và Overview có ghi lại hành động. README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Nút Take back control cho bạn thu hồi quyền ngay.
Harness tốt không làm AI thông minh hơn, nó chỉ làm AI bớt quên và bạn bớt phải canh.
Ông T
C.Quản lý chi phí khi dùng AI nhiều
Nếu bạn chạy nhiều agent, token tăng rất nhanh. Bảng điều khiển hiển thị token và chi phí cạnh Claude Code. README cũng có plugin ruflo-cost-tracker để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí. Cài bằng /plugin install trong Claude Code theo đúng mẫu lệnh ở phần cài đặt, rồi mở /ruflo để theo dõi.
D.Người dùng Codex muốn thêm bộ nhớ và công cụ
Bạn dùng Codex thay vì Claude Code. Hãy khai báo MCP server với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Codex sẽ gọi được các công cụ của Ruflo, trong đó có bộ nhớ. README không ghi chi tiết từng công cụ Codex nhìn thấy, nên bạn xem danh sách công cụ MCP trong client để biết chính xác.
VI.Lỗi hay gặp và cách xử lý
Tư liệu không có mục xử lý sự cố riêng, nên các điểm dưới đây dựa trên yêu cầu ghi trong README và những lỗi rất dễ gặp với loại công cụ này.
- Lệnh
npxbáo lỗi hoặc không chạy. Kiểm tra bản Node bằngnode --version. Repo yêu cầu Node 20 trở lên. Cập nhật Node rồi chạy lại. - Mở Claude Code nhưng không thấy gì mới. Cấu hình chỉ được nhận ở lần khởi động tiếp theo. Hãy đóng hẳn Claude Code, mở lại đúng thư mục đã chạy
init. Với plugin, chạy/reload-plugins. - Lệnh
/plugin installkhông được. Đường plugin cần Claude Code từ 2.1.287 trở lên. Lệnh cài từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước. - Bị thêm file lạ vào dự án. Đó là hành vi của
init(.claude/,.claude-flow/,CLAUDE.md…). Nếu không muốn, hãy dùng đường plugin, không thêm file nào. Bạn cũng nên chạy trong dự án có Git để dễ xem lại thay đổi. - Claude từ chối thao tác trong console. Mức quyền mặc định là read + ask, nên hành động ghi hoặc quản lý sẽ bị từ chối. Đây là thiết kế an toàn. Nâng mức quyền trong Settings → Claude control nếu bạn chắc chắn, và đừng bật
autokhi chưa quen. - Cài cùng một plugin ngoài từ hai kho. README cảnh báo: với các plugin ngoài như
agentic-qe-fleet,agentdb,agentic-flow, chỉ nên cài từ một kho, nếu không mod và lệnh có thể bị nạp hai lần.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh, chỉ một lệnh. Hỗ trợ cả Claude Code, Codex và các MCP client. Có bảng điều khiển để nhìn thấy agent, token, chi phí. Quyền của Claude trong console được chặn theo mức, mặc định thận trọng. Giấy phép MIT, và repo vẫn được cập nhật trong 3 tháng gần đây.
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 hãy bắt đầu chỉ với init rồi dùng như bình thường. README tự nói rõ nhiều phần là "khái niệm" chứ không phải bằng chứng thực thi, ví dụ các video demo dùng dữ liệu mẫu và không chứng minh swarm hoàn thành việc thật hay bộ nhớ gợi lại đúng. Đường init thêm khá nhiều file vào dự án. Mod chạy bằng quyền tài khoản bạn, không sandbox. Và chi phí token có thể tăng khi chạy nhiều agent cùng lúc.
Khi nên chọn cách khác. Nếu bạn chỉ cần Claude Code chạy một việc nhỏ, dùng thẳng Claude Code là đủ, thêm harness chỉ làm phức tạp. Nếu bạn chỉ muốn thử vài lệnh, đường plugin sạch hơn. Nếu bạn cần cam kết về bảo mật dữ liệu hay hiệu năng cụ thể, README không đưa số liệu đủ để mình khẳng định, hãy tự thử trên một dự án nhỏ, không chứa dữ liệu nhạy cảm, trước khi dùng cho việc quan trọng.
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 bạn dùng và sửa mã nguồn tự do. Tuy nhiên bạn vẫn cần quyền dùng Claude Code hoặc Codex, và chi phí của các dịch vụ AI đó nằm ngoài Ruflo. Tư liệu chưa nói chi tiết về giá của các dịch vụ này.
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 cài dạng plugin, không thêm file vào dự án, dùng `/plugin marketplace add ruvnet/ruflo` rồi `/plugin install ruflo-core@ruflo` trong Claude Code.
Cần phiên bản Node hay Claude Code nào?
package.json yêu cầu Node 20.0.0 trở lên. Đường cài plugin cần Claude Code 2.1.287 trở lên, và lệnh cài plugin từ terminal cần 2.1.292 trở lên.
Ruflo có dùng được với Codex không?
Có. README nói Codex và các MCP client 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.
Claude có tự ý làm bậy trong bảng điều khiển được không?
Theo README, mức mặc định là read + ask, tức Claude chỉ được xem và phải hỏi bạn. Các hành động mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả ở chế độ auto. Nút Take back control cho bạn thu hồi quyền bất cứ lúc nào.
Chạy Ruflo có cần GPU không, có chạy trên Windows được không?
Tư liệu chưa có thông tin về yêu cầu GPU hay hệ điều hành cụ thể. Điều chắc chắn là cần Node 20 trở lên. Bạn nên xem README và thư mục docs của repo, hoặc thử `npx ruflo@latest init` trên một dự án nhỏ.
Ruflo khác gì dùng Claude Code thuần?
Ruflo là lớp bao quanh Claude Code và Codex, thêm đội agent, bộ nhớ qua các phiên, hook tự định tuyến và bảng điều khiển. Claude Code thuần chỉ có công cụ gốc của nó. README cho biết Ruflo dành cho việc nhiều bước, còn việc nhỏ thì có thể không cần.


