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 là Claude Flow) là bộ khung điều phối agent AI, bọc quanh Claude Code và Codex để thêm swarm agent, bộ nhớ qua các phiên, hook và máy chủ MCP. Bạn dùng nó để giao việc lớn cho nhiều agent phối hợp thay vì một cuộc trò chuyện đơn lẻ. Cài khá dễ: chỉ cần Node 20 trở lên và chạy một lệnh npx trong thư mục dự án.
Ruflo là một "agent harness" (bộ khung điều phối) bọc quanh Claude Code và Codex. Nói đơn giản: mô hình AI lo viết code, còn Ruflo cho nó thêm công cụ, bộ nhớ, vòng lặp làm việc và các lớp kiểm soát để làm được việc dài hơi. Tác giả mô tả nó bằng công thức "Agent = Model + Harness".
Repo này dành cho lập trình viên, kể cả người mới, đã dùng Claude Code hoặc Codex và thấy một cuộc trò chuyện đơn lẻ không đủ cho việc lớn. Nếu bạn làm văn phòng hay kinh doanh nhưng có người trong nhóm biết code, bài này vẫn giúp bạn hiểu nó làm được gì để bàn việc với họ.
Điểm đáng giá nhất: bạn chỉ cần chạy một lệnh init, rồi tiếp tục dùng Claude Code như bình thường. Phần định tuyến tác vụ, ghi nhớ kinh nghiệm và phối hợp nhiều agent chạy ngầm. Repo hiện có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, viết chủ yếu bằng TypeScript. Tên gói trên npm vẫn là claude-flow, nhưng lệnh khuyến nghị là ruflo.
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à bảng điều khiển, cài bằng một lệnh npx.
I.Ruflo làm được gì
README giới thiệu rất nhiều thứ. Mình gom lại thành những ý bạn dễ dùng nhất.
Nhiều agent làm chung một việc (swarm). Thay vì một AI làm tuần tự, Ruflo cho các agent chuyên biệt tự chia việc theo nhóm. README ghi cài kiểu đầy đủ có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế là bạn có thể ra một yêu cầu như "rà soát cả repo, viết test cho chỗ rủi ro nhất" và để cả nhóm xử lý.
Bộ nhớ qua các phiên. Agent nhớ được thứ đã làm ở lần trước, nên 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ũng nói hệ thống "học" từ các tác vụ thành công để định tuyến tốt hơn về sau. Phần này cần embedding và các module học được cấu hình, không phải tự nhiên có sẵn.
Hook tự động. Sau init, hook sẽ định tuyến tác vụ và điều phối agent ở nền. README nhắn thẳng người mới: 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 bình thường.
Bảng điều khiển (console). Đây là "buồng lái" cạnh Claude Code: theo dõi workflow, agent, mô hình, token và chi phí; mở log và kết quả từng lần chạy để tìm lỗi, xem lại, so sánh. Gõ /ruflo trong Claude Code để mở.
Cho Claude điều khiển, bạn đặt giới hạn. Trong Settings → Claude control bạn chọn mức read, write, manage hoặc full, cùng chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask. Các hành động dùng mạng, tốn tiền hoặc phá huỷ vẫn phải xác nhận kể cả khi để auto. Có nút Take back control để thu lại quyền ngay.
Hệ thống 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-testgen tìm chỗ thiếu test và tạo test, ruflo-cost-tracker theo dõi token và đặt ngân sách, ruflo-aidefence chặ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 an toàn. Phần này dành cho nhu cầu nâng cao, người mới có thể bỏ qua.
Ngoài ra README nhắc tới việc dùng Codex và client MCP khác, và có lệnh npx ruflo init --grok cho Grok Build.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js 20.0.0 trở lên. Đây là yêu cầu trong
package.json. - Claude Code đã cài, hoặc Codex / một client MCP khác nếu bạn dùng các công cụ đó.
- Nếu đi đường plugin: Claude Code phiên bản 2.1.287 trở lên. Lệnh cài từ terminal (
claude plugin install ...) cần 2.1.292 trở lên. - Một thư mục dự án để chạy lệnh
inittrong đó.
README không nói rõ yêu cầu hệ điều hành, phần cứng hay API key riêng cho Ruflo. Bạn dùng tài khoản và quyền truy cập sẵn có của Claude Code hoặc Codex. Nếu muốn biết thêm, xem README.md, thư mục docs/ và file CLAUDE.md trong repo.
Các "mod" của Ruflo chạy với đúng quyền tài khoản của bạn và không bị đặt trong sandbox. README khuyên đọc mã nguồn trước khi cài. Phần chi phí token phụ thuộc vào nhà cung cấp mô hình bạn dùng, nên hãy theo dõi bằng console hoặc plugin cost-tracker.
III.Cài đặt từng bước
Có ba đường: cài đầy đủ bằng npx (README gọi là phù hợp cho dùng thật), cài chỉ plugin cho Claude Code (không thêm file vào dự án), và nối vào Codex hoặc client MCP khác. Mình hướng dẫn đường đầu trước.
- Kiểm tra NodeChắc chắn máy có Node 20 trở lên
- Chạy initMở terminal trong thư mục dự án và chạy npx ruflo@latest init
- Mở lại Claude CodeMở Claude Code ở cùng thư mục để nó nhận agent, hook, bộ nhớ
- Mở bảng điều khiểnGõ /ruflo trong Claude Code
- Giao việc thửDán một yêu cầu thật để xem swarm chạy
A.Kiểm tra Node
Mở terminal (PowerShell trên Windows, Terminal trên macOS) và gõ:
node --versionSố hiện ra phải từ v20 trở lên. Nếu thấp hơn hoặc báo không tìm thấy lệnh, bạn cần cài hoặc nâng cấp Node trước.
B.Chạy init trong thư mục dự án
Chỗ người mới hay vấp nhất là mở terminal sai thư mục. Hãy cd vào đúng thư mục dự án bạn định làm việc, rồi chạy:
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và máy chủ MCP của Ruflo vào dự án. Theo README bảng so sánh, cách này tạo các thư mục .claude/, .claude-flow/ cùng file CLAUDE.md và một số file phụ trợ. Nếu dự án đã có CLAUDE.md của bạn, hãy sao lưu hoặc dùng git để xem phần thay đổi.
Nếu muốn thiết lập có hỏi đáp từng bước, README có lệnh:
npx ruflo@latest init wizardC.Mở Claude Code và giao việc
Mở Claude Code trong cùng thư mục. Claude Code sẽ nhận cấu hình mới ở lần khởi động kế tiếp, nên nếu đang mở sẵn thì hãy đóng và mở lại. Sau đó thử một yêu cầu 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 khuyên cứ dùng nguyên câu mẫu tiếng Anh cho lần đầu, để chắc chắn khớp với cách README đã mô tả.
D.Cách 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 từ 2.1.287. Gõ lần lượt 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
/rufloGiải thích ngắn: hai lệnh đầu thêm "chợ" plugin rồi cài phần lõi, ruflo-console là bảng điều khiển, ruflo-mods định tuyến prompt và áp chính sách. /reload-plugins nạp lại để dùng ngay. Nếu muốn thêm plugin khác, cú pháp tương tự, ví dụ ruflo-swarm, ruflo-rag-memory như trong README.
Từ terminal thường, trên Claude Code 2.1.292 trở lên:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý: plugin chỉ cho bạn các lệnh gạch chéo và định nghĩa agent. Hook thì không có. Vì vậy bản đầy đủ (init) mới là "vòng lặp trọn vẹn".
E.Cách thay thế: dùng với Codex hoặc client MCP khác
Cấu hình client của bạn với command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Nghĩa là client sẽ tự chạy máy chủ MCP của Ruflo khi cần. Cách điền cụ thể vào giao diện từng client mình không có thông tin, bạn xem tài liệu của chính client đó.
F.Tuỳ chọn: bảng điều khiển trong terminal thường
Bảng điều khiển chạy được độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain nếu muốn in ra một khung hình duy nhất cho script.
IV.Kiểm tra đã chạy được chưa
Theo README, các dấu hiệu sau cho thấy cài thành công:
- Sau
initvà khởi động lại Claude Code, gõ/ruflosẽ mở bảng điều khiển. - Nếu đi đường plugin, gõ
/pluginvà xem các mod xuất hiện ở dòng "active mods". - Trong console, lệnh
/ruflo marketmở Plugin Catalog, liệt kê 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). - Với bảng điều khiển độc lập,
npx ruflo tuihiện giao diện terminal.
Bài kiểm tra tốt nhất là bài "tạo mission" mà README mô tả: mở /ruflo, vào Settings → Claude control và chọn write + ask, rồi bảo Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status." Bạn duyệt hành động tạo, sau đó kiểm tra mục Missions có mục tiêu đó và Overview ghi lại hành động. Lưu ý: tạo mission không có nghĩa tính năng dark mode đã được viết.
V.Dùng vào việc thật
A.Dev nhận một repo lạ và cần rà soát nhanh
Bạn vừa nhận bảo trì một dự án cũ, chưa có test. Chạy npx ruflo@latest init trong thư mục dự án, mở lại Claude Code rồi 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ả bạn mong đợi: các agent tìm module rủi ro nhất, viết test cho nó và báo lại phần đã đổi. Hãy xem kỹ diff và chạy test trước khi giữ lại.
Agent không phải cứ chạy là xong việc — có bộ khung kiểm soát bên cạnh, bạn mới yên tâm giao việc dài.
Ông T
B.Trưởng nhóm muốn giám sát chi phí và tiến độ
Trong nhóm có người chạy agent cả buổi mà không ai biết đang tốn bao nhiêu. Cài phần console và mods bằng plugin, rồi gõ /ruflo để xem workflow, agent, mô hình, token và chi phí cạnh Claude Code. README cũng liệt kê plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Cài theo cùng mẫu:
/plugin install ruflo-cost-tracker@rufloKết quả: bạn thấy được lần chạy nào tốn nhiều và mở log để xem vì sao.
C.Người mới muốn cho Claude thao tác bảng điều khiển nhưng sợ mất kiểm soát
Vào Settings → Claude control, đặt mức write và duyệt ask. Khi bạn nhờ "tạo mission để thêm nút chuyển giao diện tối", Claude sẽ mở trang Missions, điền mục tiêu và dừng chờ bạn xác nhận. Nếu thấy không ổn, bấm Take back control; các lệnh sau đó của Claude sẽ bị từ chối cho tới khi bạn trả quyền lại. Đây là cách làm quen an toàn nhất vì mọi thứ đều có nút dừng.
D.Dùng Codex hoặc client khác nhưng vẫn muốn bộ nhớ và công cụ của Ruflo
Bạn không dùng Claude Code mà dùng Codex. Cấu hình client với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Client sẽ gọi được các công cụ của Ruflo qua MCP, không cần cài thêm gì vào dự án. Muốn thiết lập có hướng dẫn cho một dự án cụ thể thì chạy npx ruflo@latest init wizard.
VI.Lỗi hay gặp và cách xử lý
Chạy npx báo lỗi hoặc cú pháp lạ. Nguyên nhân thường là Node cũ. Kiểm tra bằng node --version; package.json yêu cầu từ 20.0.0. Nâng Node lên rồi chạy lại.
Cài xong nhưng Claude Code không thấy gì. README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy đóng hẳn và mở lại Claude Code trong đúng thư mục bạn đã chạy init. Với plugin, nhớ chạy /reload-plugins.
Lệnh /plugin install hoặc claude plugin install không chạy. Đường plugin cần Claude Code 2.1.287 trở lên (lệnh từ terminal cần 2.1.292). Cập nhật Claude Code trước khi thử lại.
Plugin bị nạp hai lần. README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow: chỉ cài từ một marketplace, không cài từ cả marketplace gốc lẫn của Ruflo, nếu không mod và lệnh sẽ bị nạp đôi.
Claude bị từ chối hành động trong console. Đây là thiết kế. Hành động vượt quyền bạn đặt sẽ bị chặn, và các hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận. Muốn cho phép thì nâng mức quyền trong Settings → Claude control, và chỉ làm khi bạn đã hiểu hậu quả.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh, không phải tự ráp từng phần. Có nhiều lớp kiểm soát (mức quyền, xác nhận, nút lấy lại quyền). Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây, cộng đồng lớn. Bảng điều khiển giúp nhìn thấy agent đang làm gì và tốn bao nhiêu.
Giới hạn. Hệ sinh thái rất rộng: 48 plugin, hàng trăm công cụ, nên người mới dễ choáng. Cứ bắt đầu từ lệnh init và dùng Claude Code như thường. README cũng thẳng thắn rằng các đoạn demo dùng dữ liệu mẫu hoặc phát lại khung hình, không phải bằng chứng đã hoàn thành việc swarm hay nhớ lại bộ nhớ. Phần "tự học" cần embedding và module được cấu hình. Mod chạy với quyền tài khoản của bạn, không có sandbox, nên cần đọc mã trước khi cài.
Khi nên chọn cách khác. Nếu bạn chỉ cần trợ lý viết code cho tác vụ nhỏ, Claude Code hoặc Codex đứng riêng là đủ và gọn hơn. Nếu bạn không muốn thêm file vào dự án, hãy dùng đường plugin thay vì init. Nếu bạn không biết lập trình và không có ai hỗ trợ kỹ thuật, công cụ này sẽ khó tận dụng hết.
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 miễn phí sử dụng. Tuy nhiên README không nói về chi phí của nhà cung cấp mô hình. Khi agent chạy qua Claude Code hoặc Codex, bạn vẫn dùng tài khoản và hạn mức của các dịch vụ đó.
Ruflo có 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 chắc chắn là cần Node 20 trở lên và lệnh cài là `npx ruflo@latest init`. Nếu gặp vấn đề riêng trên Windows, hãy xem README và phần issue trong repo.
Có cần GPU không?
README ở phần mình đọc không nêu yêu cầu GPU cho cách cài cơ bản. Một plugin tên ruflo-ruvector được mô tả là tìm kiếm tăng tốc bằng GPU, nhưng đó là plugin tuỳ chọn. Với cách cài thông thường, chưa có thông tin cho thấy bắt buộc.
Ruflo khác gì dùng Claude Code đơn thuần?
Claude Code là công cụ viết code. Ruflo là lớp bọc phía ngoài, thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook tự động và bảng điều khiển. Bạn vẫn làm việc trong Claude Code như bình thường; Ruflo chạy phối hợp ở nền.
Cài plugin và chạy init khác nhau thế nào?
Plugin không thêm file nào vào dự án, chỉ cho lệnh gạch chéo và định nghĩa agent, và không có hook. Còn `npx ruflo@latest init` cài vòng lặp đầy đủ gồm agent, lệnh, skill, máy chủ MCP, hook và daemon, đồng thời tạo các thư mục như .claude/ và .claude-flow/ cùng file CLAUDE.md.
Dùng Ruflo có an toàn không, Claude có tự ý làm bậy 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, cùng chế độ ask hoặc auto, mặc định là read + ask. Hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận. Tuy nhiên các mod chạy với quyền tài khoản của bạn và không bị sandbox, nên hãy đọc mã trước khi cài.
Có 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: cấu hình command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`. Cách điền vào từng client cụ thể chưa có trong tư liệu, bạn xem hướng dẫn của client đó.


