Ruflo: điều phối nhóm 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 là một agent harness (lớp điều phối) bao quanh Claude Code và Codex. Nó thêm các agent chuyên biệt, hook, bộ nhớ dùng lại giữa các phiên và máy chủ MCP vào dự án của bạn. Cài chỉ cần một lệnh npx trong thư mục dự án và cần Node 20 trở lên, nên khá dễ với người đã quen dùng terminal.
Ruflo là một "agent harness" mã nguồn mở (giấy phép MIT), bao quanh Claude Code và Codex. Nói đơn giản: mô hình AI chỉ biết viết, còn harness là bộ đồ nghề giúp nó làm việc thật, gồm công cụ, bộ nhớ, vòng lặp và các giới hạn kiểm soát. Ruflo là phần đồ nghề đó. Trước đây dự án có tên Claude Flow, nay đổi tên thành Ruflo.
Bạn nên xem repo này nếu đang dùng Claude Code (hoặc Codex) và muốn nó làm việc có tổ chức hơn: giao một việc lớn cho cả nhóm agent, để chúng nhớ lại kinh nghiệm từ các lần trước, và có bảng điều khiển để theo dõi. Người mới lập trình hay người làm văn phòng đã biết mở terminal đều thử được, vì cài đặt chỉ một lệnh.
Điểm đáng giá nhất theo README: sau khi chạy init, bạn cứ dùng Claude Code như bình thường. Hệ thống hook tự định tuyến công việc, học từ các mẫu làm tốt và điều phối agent ở phía sau. 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. Repo hiện có khoảng 81.600 sao và 9.600 fork, ngôn ngữ chính là TypeScript, và vẫn được cập nhật trong 3 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ớ qua nhiều phiên, swarm nhiều agent và cảnh báo an toàn. Cài bằng một lệnh npx.
I.Ruflo làm được gì
Ruflo không phải một ứng dụng chạy riêng. Nó là lớp bổ sung cho Claude Code và Codex. Các nhóm tính năng chính theo README:
- Agent chuyên biệt và swarm. Ruflo thêm hàng trăm agent đã định nghĩa sẵn vai trò (README nêu 100+ agent). Chúng có thể phối hợp thành "swarm", tức một nhóm agent chia việc cho nhau. Lợi ích: với việc lớn như rà soát cả repo, bạn không phải ngồi tự chia nhỏ từng bước.
- Bộ nhớ qua nhiều phiên. Agent nhớ lại kinh nghiệm giữa các lần làm việc, và bộ nhớ này hỗ trợ tìm kiếm vector. Lợi ích: bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code.
- Tự học. README mô tả một vòng học: bộ nhớ đưa kinh nghiệm hữu ích quay lại để định tuyến công việc tốt hơn. README cũng ghi chú đây là sơ đồ khái niệm, và việc học vẫn cần embedding cùng các module học được cấu hình.
- Bảng điều khiển (console). Một "buồng lái" cạnh Claude Code để theo dõi workflow, agent, mô hình, token và chi phí. Bạn mở log của agent, tìm kiếm, xem lại các lần chạy lỗi, phát lại và so sánh.
- Cho Claude điều khiển bảng điều khiển, nhưng bạn đặt giới hạn. Trong Settings có mục Claude control với các mức
read,write,manage,fullvà chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. 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. - Plugin. Có 48 plugin (cộng thêm 3 plugin bên ngoài) chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps... Ví dụ
ruflo-swarmđiều phối nhiều agent,ruflo-testgentìm test còn thiếu và sinh test,ruflo-cost-trackertheo dõi token và đặt ngân sách,ruflo-aidefencechặn prompt injection và phát hiện dữ liệu cá nhân. - Liên kết nhiều máy (federation). Agent trên các máy khác nhau có thể trao đổi với nhau mà README nói là không làm lộ dữ liệu.
- Dùng được với nhiều client. Ngoài Claude Code còn có Codex và các client MCP khác. README cũng có dòng lệnh cho Grok Build.
II.Cần chuẩn bị gì
Tư liệu của repo chỉ nêu rõ vài điều sau:
- Node.js từ 20.0.0 trở lên.
package.jsonyêu cầu như vậy. Lệnhnpxđi kèm Node. - Claude Code (hoặc Codex, hoặc một client MCP khác). Nếu cài theo đường plugin của Claude Code 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. Cách cài chính của Ruflo ghi file vào thư mục này.
README không nói rõ về hệ điều hành, yêu cầu GPU hay API key nào cho bước cài cơ bản. Bạn đang dùng Claude Code thì dùng tài khoản đã có của nó. Phần học và embedding có thể cần cấu hình thêm, xem tài liệu trong thư mục docs/ của repo.
Ruflo chạy cùng Claude Code, nên mỗi tác vụ swarm có thể tốn token và tiền như khi bạn dùng Claude Code thường, thậm chí nhiều hơn vì có nhiều agent. Hãy thử với việc nhỏ trước và theo dõi chi phí trong console.
III.Cài đặt từng bước
Ruflo có hai đường cài. Đường chính là chạy npx ruflo@latest init trong dự án. Đường thứ hai là cài plugin trong Claude Code, không thêm file nào vào dự án. Phần này hướng dẫn đường chính trước.
- Mở terminal đúng thư mụcĐi vào thư mục dự án mà bạn dùng với Claude Code
- Chạy initChạy một lệnh npx để thêm agent, hook, bộ nhớ và máy chủ MCP
- Mở lại Claude CodeMở Claude Code trong cùng thư mục để nó nạp Ruflo
- Giao thử một việcDán một câu lệnh mẫu để thử swarm
- (Tuỳ chọn) Cài plugin hoặc nối CodexChọn đường plugin hoặc cấu hình MCP
A.Mở terminal ở thư mục dự án
Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. init ghi file vào thư mục hiện tại, nên hãy vào đúng thư mục dự án của bạn trước. Nếu chưa có dự án, bạn tạo một thư mục trống và vào đó.
cd ten-thu-muc-du-an-cua-banĐổi ten-thu-muc-du-an-cua-ban thành tên thư mục thật của bạn. Trên Windows bạn có thể dùng PowerShell hoặc terminal tích hợp trong trình soạn thảo.
B.Chạy lệnh init
Đây là lệnh chính của README:
npx ruflo@latest initnpx tải bản Ruflo mới nhất và chạy lệnh init. Theo README, bước này thêm agent, hook, bộ nhớ và máy chủ MCP của Ruflo vào dự án. Bảng so sánh trong README cho biết cách cài này tạo các thư mục .claude/, .claude-flow/, file CLAUDE.md, các file hỗ trợ và settings trong dự án. Nếu dự án đã có CLAUDE.md riêng, bạn nên sao lưu hoặc dùng Git để xem lại thay đổi sau khi chạy.
Nếu muốn thiết lập theo kiểu hỏi đáp, README có 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 Ruflo ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn một phiên Claude Code từ trước khi chạy init, hãy thoát và mở lại.
D.Giao thử một việc
Bạn dán câu lệnh 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 nhờ một swarm rà soát repo, tìm module rủi ro nhất, viết test cho nó rồi tóm tắt những gì đã đổi. Bạn có thể viết bằng tiếng Việt, nhưng mình giữ nguyên câu của README để bạn thấy chính xác nó hoạt động với mẫu nào.
E.Đường thay thế: chỉ cài plugin trong Claude Code
Đường này không thêm file nào vào dự án và cần Claude Code 2.1.287 trở lên. Bạ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ừng dòng làm gì: dòng đầu thêm kho plugin của Ruflo. Ba dòng install cài lõi, bảng điều khiển và các mod. /reload-plugins nạp lại plugin, còn /ruflo mở bảng điều khiển. Nếu dùng Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý README nhắc: bản cài plugin chỉ có phần "lite". Bạn nhận lệnh gạch chéo, một số kỹ năng và định nghĩa agent, không có hook. Muốn chạy đầy đủ như tài liệu mô tả thì dùng npx ruflo@latest init.
F.Đường thay thế: Codex hoặc client MCP khác
Không cần cài vào dự án. Bạn cấu hình client với command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]Tức client sẽ tự chạy npx -y ruflo@latest mcp start để mở máy chủ MCP của Ruflo. Chỗ điền cấu hình này phụ thuộc client bạn dùng, nên xem tài liệu của chính client đó.
G.Bảng điều khiển trên terminal thường
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 duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh "kiểm tra phiên bản" riêng. Bạn có thể tự kiểm tra qua các dấu hiệu sau, đều có trong tư liệu:
- 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. Nếu bảng điều khiển hiện ra thì Ruflo đã nạp. Bảng này nằm trong pluginruflo-console, nên nếu gõ không ra thì kiểm tra lại phần plugin. - Nếu cài bằng plugin, mở
/pluginvà xemruflo-console,ruflo-modscó nằm trong dòng các mod đang bật không. - Giao câu lệnh swarm mẫu ở trên. Nếu Claude Code bắt đầu chia việc, viết test và tóm tắt, tức là mọi thứ đã nối với nhau.
- Với cách chạy terminal thường,
npx ruflo tuihiện giao diện là được.
V.Dùng vào việc thật
Ruflo hợp nhất khi bạn đã có việc cụ thể với Claude Code. Dưới đây là mấy tình huống bám đúng những gì README nêu.
A.Dev nhận một repo lạ và cần biết chỗ nào rủi ro
Bạn vừa nhận bảo trì một dự án nhỏ, chưa ai viết test. Bạn chạy init trong thư mục dự án, mở lại Claude Code rồi giao đúng 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ả bạn mong đợi: một nhóm agent đọc repo, chọn module rủi ro nhất, viết test cho nó và đưa bản tóm tắt thay đổi. Hãy xem lại test và diff trước khi giữ lại. Agent viết test đúng hướng không có nghĩa là test đã đủ.
Bạn cứ viết code, còn việc phối hợp giữa các agent để Ruflo lo.
Ông T
B.Người dùng bảng điều khiển để theo dõi một nhiệm vụ
Bạn muốn thấy Claude đang làm gì mà không phải đọc cả đống log. Sau khi cài console, mở /ruflo, vào Settings, chọn Claude control 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 thao tác tạo đang chờ trong console. Cuối cùng kiểm tra Missions có mục tiêu đó và Overview 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 làm xong. Nếu muốn dừng, bấm Take back control và các lệnh Claude gọi vào console sẽ bị từ chối cho tới khi bạn trả lại quyền.
C.Chủ doanh nghiệp nhỏ thử một plugin lẻ, không đụng vào dự án
Bạn chưa muốn thêm file vào dự án thật. Hãy chọn đường plugin: thêm kho ruvnet/ruflo, cài ruflo-core, rồi chỉ cài thêm plugin bạn cần, chẳng hạn ruflo-cost-tracker để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí, hoặc ruflo-testgen để tìm test còn thiếu. Bạn nhận về các lệnh gạch chéo và agent của plugin đó, không có file nào xuất hiện trong thư mục làm việc. Đây là cách thử rẻ nhất trước khi quyết định cài đầy đủ.
D.Dev dùng Codex hoặc client MCP khác
Bạn không dùng Claude Code mà dùng Codex hoặc một client MCP. Bạn trỏ client tới npx -y ruflo@latest mcp start như phần cài đặt ở trên. Kết quả: client đó gọi được các công cụ MCP của Ruflo, ví dụ công cụ bộ nhớ, mà không cần chạy init trong dự án. Tên công cụ cụ thể mình khuyên bạn xem trong tài liệu của repo, vì README nêu rằng tên công cụ khác nhau giữa cách cài plugin và cách cài CLI.
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 quá cũ hoặc chưa cài. Repo yêu cầu Node 20.0.0 trở lên. Mở terminal, chạy node --version để xem phiên bản. Nếu thấp hơn 20 thì cập nhật Node rồi chạy lại npx ruflo@latest init.
B.Chạy init xong mà Claude Code chưa thấy Ruflo
Thường là bạn chưa khởi động lại Claude Code. README nói Claude Code nhận Ruflo ở lần khởi động kế tiếp. Hãy thoát hẳn, mở lại ngay trong thư mục đã chạy init. Mở sai thư mục cũng là nguyên nhân hay gặp, nên kiểm tra thư mục hiện tại có .claude/ và CLAUDE.md chưa.
C.Lệnh /plugin hoặc /ruflo không hoạt động
Đườ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 nếu bản bạn dùng cũ hơn. Sau khi cài plugin, đừng quên /reload-plugins rồi mở /plugin để xem plugin đã bật 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 và agentic-flow: chỉ nên cài từ một kho duy nhất. Nếu bật từ cả hai kho, mod và lệnh có thể bị nạp hai lần. Hãy chọn một nơi cài và gỡ bản còn lại.
E.Lo ngại về quyền hạn của mod và Claude control
README nói rõ mod chạy với quyền tài khoản của bạn và không nằm trong sandbox, nên cần đọc mã trước khi cài. Với Claude control, hãy giữ mức mặc định read + ask, chỉ nâng khi thật sự cần. Nếu Claude làm gì đó bạn không muốn, bấm Take back control rồi xem nhật ký hành động trực tiếp trong console.
VII.Có nên dùng không
Điểm mạnh. Cài đặt một dòng, giấy phép MIT, dự án còn được cập nhật. Có cả đường cài "nhẹ" bằng plugin và đường cài đầy đủ. Hỗ trợ nhiều client (Claude Code, Codex, client MCP khác). Có bảng điều khiển theo dõi agent, token và chi phí, cùng cơ chế giới hạn quyền cho Claude khi điều khiển console.
Giới hạn. Ruflo rất rộng: hàng chục plugin, hàng trăm công cụ MCP. Người mới dễ bị ngợp, dù README nói bạn chỉ cần dùng Claude Code như bình thường sau init. README cũng tự nói vài điều đáng chú ý: sơ đồ tự học là khái niệm, bản demo hoạt ảnh dùng dữ liệu mẫu, và các bản demo đó không phải bằng chứng cho việc swarm đã làm xong việc hay bộ nhớ đã nhớ lại đúng. Nghĩa là bạn nên tự kiểm tra kết quả trên dự án của mình thay vì tin vào lời quảng cáo. Đường cài plugin chỉ cho một phần nhỏ so với cài đầy đủ, và init thêm khá nhiều file vào dự án. Chi phí token khi chạy nhiều agent cũng là thứ bạn cần tự canh.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời nhanh một việc đơn giản, thêm một lớp điều phối có thể là thừa. Nếu bạn không muốn bất kỳ file lạ nào xuất hiện trong dự án, hãy dùng đường plugin hoặc cấu hình MCP. Còn nếu việc của bạn lớn, lặp lại và cần trí nhớ giữa các phiên, Ruflo đáng thử trên một dự án nhỏ trước.
Câu hỏi thường gặp
Ruflo có miễn phí không?
Mã nguồn Ruflo theo giấy phép MIT nên dùng tự do. Nhưng nó chạy cùng Claude Code hoặc Codex, nên chi phí dùng mô hình vẫn tính theo tài khoản và gói của chính các công cụ đó. README có plugin theo dõi token và đặt ngân sách, còn gói giá cụ thể thì tư liệu chưa nói.
Cài Ruflo có khó không?
Đường chính chỉ là một lệnh: npx ruflo@latest init, chạy trong thư mục dự án, rồi mở lại Claude Code. Bạn cần Node 20 trở lên. Nếu chưa quen terminal thì chỉ vướng ở việc mở đúng thư mục.
Ruflo có cần GPU không?
Tư liệu về repo không nêu yêu cầu GPU cho bước cài và dùng cơ bản. README có nhắc một plugin tìm kiếm tăng tốc bằng GPU, nhưng đó là plugin tuỳ chọn. Yêu cầu phần cứng chi tiết thì chưa có thông tin, bạn xem thư mục docs trong repo.
Ruflo khác gì dùng Claude Code thuần?
Claude Code thuần chỉ có mô hình và các công cụ sẵn có. Ruflo thêm lớp harness gồm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook, bảng điều khiển và các lớp bảo vệ. Sau khi cài, bạn vẫn dùng Claude Code như bình thường, phần điều phối chạy 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ạn cấu hình command là npx với arguments là -y, ruflo@latest, mcp, start. Ngoài ra còn có lệnh init cho Grok Build. Cách điền cấu hình tuỳ từng client.
Cài plugin và chạy npx ruflo init khác nhau thế nào?
Cài plugin không thêm file nào vào dự án, chỉ cho lệnh gạch chéo, một số kỹ năng và định nghĩa agent, và không có hook. Chạy init thêm .claude/, .claude-flow/, CLAUDE.md, hook, daemon và máy chủ MCP, và README gọi đây là cách dùng đầy đủ cho công việc thật.
Dữ liệu của tôi có an toàn không?
README nói Ruflo có các rào chắn bảo mật và phần liên kết nhiều máy được thiết kế để không làm lộ dữ liệu. Với Claude control, mức mặc định là read + ask, và hành động liên quan mạng, chi tiêu hay phá huỷ luôn cần xác nhận. Mod chạy với quyền tài khoản của bạn và không có sandbox, nên bạn cần đọc mã trước khi cài.


