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 "harness" bao quanh Claude Code và Codex, thêm nhiều agent chuyên biệt, bộ nhớ dài hạn, hook và MCP server. Bạn dùng nó để giao việc lớn cho một nhóm agent phối hợp với nhau thay vì một AI làm một mình. Cài khá đơn giản: một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên.
Ruflo là một lớp điều phối (harness) đặt quanh Claude Code và Codex. Nó bổ sung những thứ mà một AI viết code đơn lẻ thường thiếu: nhiều agent chuyên biệt, bộ nhớ giữ lại giữa các phiên, hook tự chạy và một MCP server. 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, giấy phép MIT.
Nếu bạn đã dùng Claude Code và thấy nó hay "quên" việc cũ, hoặc muốn giao một việc lớn như "rà soát cả repo, viết test, tóm tắt thay đổi" cho nhiều agent cùng làm, Ruflo nhắm đúng vào chỗ đó. Người mới cũng dùng được: sau khi cài, bạn cứ dùng Claude Code như bình thường, phần điều phối chạy nền.
Điểm đáng giá nhất là cách cài rất ngắn gọn: một lệnh trong thư mục dự án, mở lại Claude Code là xong. Ngoài ra còn có đường cài "nhẹ" qua plugin của Claude Code, không thêm file nào vào dự án của bạn.
ruvnet/ruflo
Ruflo là lớp điều phối bao quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server vào dự án chỉ với một lệnh npx.
I.Ruflo làm được gì
Theo README, công thức là "Agent = Model + Harness". Model viết code, còn harness đưa cho nó công cụ, bộ nhớ, vòng lặp và các giới hạn kiểm soát. Ruflo đóng vai harness đó. Cụ thể:
- Nhiều agent chuyên biệt chạy thành nhóm (swarm). README nói bản cài bằng CLI có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: bạn giao một việc lớn, hệ thống chia cho nhiều agent thay vì để một agent ôm hết.
- Bộ nhớ qua nhiều phiên. Agent nhớ được kinh nghiệm từ các việc trước và dùng lại. Bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code.
- Hook tự định tuyến và học. Sau khi
init, hook sẽ tự chuyển việc cho đúng agent và ghi lại mẫu làm việc thành công. Bạn không phải học hết 406 công cụ MCP hay 61 lệnh CLI mà README nhắc tới. - Console "buồng lái" ngay cạnh Claude Code. Gõ
/ruflođể xem workflow, agent, model, token và chi phí. Bạn có thể mở log từng lần chạy, tìm kiếm, xem lỗi, chạy lại và so sánh. - Cho Claude điều khiển console, nhưng bạn đặt giới hạn. Trong Settings có mục Claude control với bốn mức
read,write,manage,fullvà hai chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận, kể cả khi đểauto. - Hệ plugin lớn. README liệt kê 48 plugin, 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-testgentìm chỗ thiếu test và tạo test,ruflo-cost-trackertheo dõi token và đặt ngân sách,ruflo-aidefencechặn prompt injection. - Liên kết (federation). Agent trên các máy khác nhau có thể trao đổi với nhau. Phần này dành cho người dùng nâng cao, người mới chưa cần đụng tới.
- Dùng được với Codex và client MCP khác. Chỉ cần trỏ client tới lệnh
npx -y ruflo@latest mcp start.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu rõ vài thứ:
- Node.js từ 20.0.0 trở lên (theo
package.json). Bạn cần cónpxđi kèm Node. - Claude Code đã cài, nếu bạn đi đường
inithoặc đường plugin. Riêng đường plugin cần Claude Code 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. Với đường
init, Ruflo sẽ thêm file vào chính thư mục này. - Nếu dùng Codex hoặc client MCP khác: client đó phải cho phép khai báo một MCP server bằng lệnh và tham số.
README không nói về yêu cầu GPU, hệ điều hành cụ thể hay API key riêng cho Ruflo. Các thông tin đó chưa có trong tư liệu mình có. Bạn vẫn cần tài khoản/quyền truy cập Claude Code hoặc Codex như bình thường để agent làm việc.
Một chi tiết dễ gây rối: tên gói npm trong repo là claude-flow (có lệnh CLI), nhưng README hướng dẫn gọi ruflo qua npx. Bạn cứ làm đúng theo README là được.
III.Cài đặt từng bước
Có ba đường: (A) init vào dự án, (B) chỉ cài plugin trong Claude Code, (C) nối Codex hoặc client MCP khác. Phần dưới đi theo đường A trước vì README gọi đây là cách chính. README nói đường này hợp cho dùng thật vì mọi thứ chạy đúng như tài liệu.
- Mở terminal đúng thư mụcVào thư mục dự án mà bạn muốn Ruflo hỗ trợ
- Chạy initGõ npx ruflo@latest init để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude CodeMở Claude Code ở cùng thư mục để nó nạp cấu hình mới
- Giao việc thửĐưa một việc thật và để Ruflo điều phối
- (Tuỳ chọn) Cài bằng pluginCách nhẹ, không thêm file vào dự án
A.Mở terminal đúng thư mục dự án
Lệnh init ghi file vào thư mục hiện tại, nên chỗ này quan trọng nhất. Trên Windows, bạn có thể mở PowerShell rồi dùng cd để vào thư mục dự án. Chưa có dự án thì tạo một thư mục thử để làm quen trước.
cd duong-dan/toi/thu-muc-du-anĐổi duong-dan/toi/thu-muc-du-an thành đường dẫn thật trên máy bạn.
B.Chạy lệnh init
Đây là lệnh chính theo README:
npx ruflo@latest initnpx tải và chạy bản mới nhất của Ruflo mà không cần cài toàn cục. README nói init thêm agent, hook, bộ nhớ và MCP server vào dự án. Bảng so sánh trong README cho biết bản này tạo các mục như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings trong thư mục làm việc. Nếu dự án của bạn đã có CLAUDE.md, hãy sao lưu hoặc dùng Git để xem lại thay đổi sau khi chạy.
Muốn cài theo kiểu hỏi đáp từng bước, README có lệnh:
npx ruflo@latest init wizardInit sẽ thêm file vào dự án. Hãy thử trên một thư mục có Git hoặc đã sao lưu, để bạn dễ xem Ruflo đã thay đổi gì và hoàn tác nếu cần.
C.Mở lại Claude Code và giao việc thử
Mở Claude Code ở cùng thư mục. README nói Claude Code sẽ nạp cấu hình mới ở lần khởi động kế tiếp, nên nếu Claude Code đang mở sẵn thì bạn hãy đóng và mở lại. Sau đó thử một việc thật, ví dụ 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.Câu này bảo Claude dùng swarm của Ruflo để rà soát repo, tìm module rủi ro nhất, viết test cho nó rồi tóm tắt thay đổi. Bạn có thể viết bằng tiếng Việt, nhưng README chỉ đưa ví dụ tiếng Anh nên mình giữ nguyên câu gốc.
D.Cách khác: chỉ cài plugin trong Claude Code
Đường này không thêm file nào vào dự án. README ghi nó cài công cụ lõi, console trực quan và các mod chạy trong tiến trình. 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
/rufloDòng đầu thêm "chợ" plugin của Ruflo. Ba dòng install cài từng plugin. /reload-plugins nạp lại, còn /ruflo mở console. Nếu bạn dùng Claude Code 2.1.292 trở lên và muốn cài từ terminal thường, README cho lệnh:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloCác mod chạy với quyền tài khoản của bạn và không được cô lập (sandbox). README dặn hãy đọc code trước khi cài. Plugin cũng chỉ cho bạn một phần tính năng, không đầy đủ như bản `init`.
E.Cách khác: Codex hoặc client MCP khác
Không cần cài sẵn gì thêm. Trong cài đặt MCP của client, khai báo command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Cách khai báo cụ thể (file nào, giao diện nào) tuỳ từng client. README chưa hướng dẫn chi tiết cho từng client, nên bạn xem tài liệu của client đó và thư mục docs/ trong repo.
IV.Kiểm tra đã chạy được chưa
Theo README, bạn có thể kiểm tra như sau:
- Sau
init, mở lại Claude Code trong thư mục dự án rồi gõ/ruflo. Console "buồng lái" xuất hiện là dấu hiệu tốt. - Với đường plugin, mở
/pluginvà kiểm tra các mod (ví dụruflo-console,ruflo-mods) có hiện trong dòng "active mods". - Trong thư mục dự án, nếu dùng
init, bạn sẽ thấy các mục như.claude/,.claude-flow/vàCLAUDE.mdđược tạo hoặc cập nhật. - Muốn thử giao diện terminal riêng, không cần Claude Code, chạy:
npx ruflo tuiThêm --plain nếu bạn chỉ muốn in ra một khung hình, tiện cho script. README chưa mô tả chi tiết kết quả mong đợi ngoài việc console hiện lên, nên mình không nêu thêm.
V.Dùng vào việc thật
A.Dev rà soát một dự án có sẵn
Bối cảnh: bạn nhận một repo từ đồng nghiệp, không biết chỗ nào dễ hỏng, test thì thưa thớt.
Làm thế nào: chạy npx ruflo@latest init trong repo, mở lại Claude Code rồi giao 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ả: Claude điều phối nhóm agent để xác định module rủi ro nhất, viết test và tóm tắt thay đổi. Bạn đọc phần tóm tắt, xem lại test và chạy thử trước khi giữ lại.
Bạn không cần học 406 công cụ. Cài xong cứ dùng Claude Code như bình thường, phần điều phối để Ruflo lo.
Ông T
B.Người dùng muốn "cầm lái" bằng console
Bối cảnh: bạn muốn nhìn thấy agent đang làm gì, tốn bao nhiêu token, chứ không muốn tin mù quáng.
Làm thế nào: cài console theo đường plugin (như phần trên), gõ /ruflo, vào Settings → Claude control và chọn write + ask. Rồi nhờ Claude, theo ví dụ của README: "Create a mission to add a dark mode toggle. Show me the mission and its status."
Kết quả: Claude mở mục Missions và đặt mục tiêu, bạn xác nhận thao tác tạo. Sau đó mục 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.
C.Người dùng Codex hoặc client MCP khác
Bối cảnh: bạn không dùng Claude Code mà dùng Codex, hoặc một công cụ khác hỗ trợ MCP, và muốn có bộ nhớ cùng công cụ của Ruflo.
Làm thế nào: khai báo MCP server với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"] như phần cài đặt ở trên.
Kết quả: client của bạn có thêm các công cụ MCP của Ruflo mà không cần chạy init trong dự án. Mức độ hỗ trợ cụ thể phụ thuộc client, README không cam kết chi tiết.
D.Muốn thử mà không đụng vào dự án
Bối cảnh: bạn quản lý một thư mục quan trọng và chưa muốn có thêm file lạ.
Làm thế nào: đi đường plugin. Bắt đầu với /plugin marketplace add ruvnet/ruflo, rồi cài ruflo-core. Cần thêm tính năng thì cài tiếp từng plugin, ví dụ ruflo-swarm để điều phối nhiều agent, ruflo-rag-memory cho truy xuất thông minh hơn, hay ruflo-cost-tracker để theo dõi token và ngân sách.
Kết quả: bạn có lệnh slash và định nghĩa agent mà không có file nào được thêm vào workspace. Đổi lại, README nói rõ đường này không có hook và không có đầy đủ như bản init.
VI.Lỗi hay gặp và cách xử lý
A.Node quá cũ, npx báo lỗi
package.json yêu cầu Node từ 20.0.0. Nếu máy bạn đang dùng bản cũ hơn, lệnh có thể lỗi ngay. Kiểm tra bằng node --version, cập nhật Node lên bản 20 trở lên rồi chạy lại npx ruflo@latest init.
B.Cài plugin báo không nhận lệnh
Đường plugin cần Claude Code 2.1.287 trở lên (lệnh cài từ terminal cần 2.1.292 trở lên). Nếu Claude Code của bạn cũ hơn, hãy cập nhật trước. Cài xong mà chưa thấy lệnh mới thì thử /reload-plugins, hoặc đóng và mở lại Claude Code.
C.Mở Claude Code nhưng không thấy gì mới sau init
README nói Claude Code nạp cấu hình ở lần khởi động kế tiếp. Hãy chắc là bạn mở Claude Code đúng thư mục đã chạy init. Nếu sai thư mục, nó sẽ không thấy .claude/ và các file liên quan.
D.Plugin bị nạp hai lần
Với một số plugin bên ngoài như agentic-qe-fleet, agentdb, agentic-flow, README dặn chỉ cài từ một marketplace, hoặc marketplace gốc của plugin đó hoặc của ruflo. Cài từ cả hai thì mod và lệnh bị nạp đôi. Nếu thấy lệnh bị trùng, gỡ một bản đi.
E.Claude bị từ chối khi điều khiển console
Đây là thiết kế chứ không phải lỗi. Thao tác vượt quá mức quyền bạn chọn trong Claude control sẽ bị từ chối, và các việc liên quan mạng, chi tiêu, phá huỷ luôn cần xác nhận. Nếu muốn Claude được phép nhiều hơn, bạn nâng mức quyền một cách chủ động và cân nhắc. Đừng bật auto với mức full nếu chưa hiểu rõ.
VII.Có nên dùng không
Điểm mạnh:
- Cài nhanh: một lệnh
npxvà mở lại Claude Code. - Có đường nhẹ (plugin) để thử mà không động vào dự án.
- Console cho phép nhìn, kiểm tra và chạy lại từng lần làm việc của agent, thay vì tin mù quáng.
- Quyền hạn của Claude trong console được bạn đặt rõ, mặc định là mức thấp.
- 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 lớn: 48 plugin, hàng trăm công cụ. Người mới dễ choáng, nên bắt đầu với
initrồi dùng như bình thường, đừng cố học hết. - README tự nói phần "học liên tục" mới ở mức khái niệm, và một số demo dùng dữ liệu mẫu, không chứng minh được việc swarm đã làm xong thật. Hãy tự kiểm tra kết quả.
- Bản
initthêm khá nhiều file vào dự án. Bản plugin thì nhẹ nhưng ít tính năng. - Mod 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.
- Chi phí token khi chạy nhiều agent cùng lúc: README chưa đưa số liệu cụ thể, nên hãy theo dõi bằng console hoặc plugin
ruflo-cost-tracker.
Nên chọn cách khác khi: bạn chỉ cần một AI trả lời nhanh vài câu hỏi, hoặc dự án nhỏ đến mức việc điều phối nhiều agent là thừa. Lúc đó dùng Claude Code hoặc Codex thuần sẽ đơn giản và rẻ hơ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 bạn dùng và sửa mã tự do. Tuy nhiên agent vẫn gọi Claude Code, Codex hoặc nhà cung cấp AI khác, nên chi phí của các dịch vụ đó thì bạn vẫn chịu. README chưa nêu bảng giá cụ thể.
Cài Ruflo cần phiên bản Node nào?
File package.json yêu cầu Node từ 20.0.0 trở lên. Bạn dùng lệnh npx đi kèm Node để chạy `npx ruflo@latest init`. Nếu dùng đường plugin thì cần thêm Claude Code từ 2.1.287 trở lên.
Ruflo có cần GPU không?
Tư liệu mình có không nói Ruflo bắt buộc GPU. README chỉ nhắc một plugin riêng (`ruflo-ruvector`) có tìm kiếm tăng tốc bằng GPU, đây là tính năng tuỳ chọn. Với phần còn lại, chưa có thông tin về yêu cầu phần cứng.
Chạy được trên Windows không?
README không nêu rõ danh sách hệ điều hành được hỗ trợ. Lệnh cài chỉ là `npx ruflo@latest init` nên về nguyên tắc cần Node và terminal. Bạn nên thử trên một thư mục thử trước khi dùng cho dự án quan trọng.
Khác gì so với dùng Claude Code thuần?
Ruflo là lớp bao quanh Claude Code (và Codex), thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên, hook tự định tuyến và một console theo dõi. Nó không thay thế Claude Code mà chạy cùng nó. Bạn vẫn dùng Claude Code như bình thường.
Dữ liệu và quyền truy cập có an toàn không?
README cho biết console để mức Claude control mặc định là read + ask, và các thao tác liên quan mạng, chi tiêu 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 có sandbox, nên bạn cần đọc code trước khi cài. Repo cũng có tệp SECURITY.md để bạn xem thêm.
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, bằng cách khai báo command `npx` với tham số `-y`, `ruflo@latest`, `mcp`, `start`. Cách cấu hình cụ thể tuỳ từng client và README chưa hướng dẫn chi tiết từng công cụ.


