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à lớp điều phối bọc quanh Claude Code và Codex. Nó thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên làm việc, hook và một MCP server vào dự án của bạn. Cài chỉ cần một lệnh npx và Node 20 trở lên, nên người mới cũng làm được.
ruflo là một "harness" cho AI lập trình: lớp công cụ đặt quanh Claude Code hoặc Codex để chúng có thêm agent chuyên biệt, bộ nhớ, hook và cách phối hợp nhiều agent cùng làm một việc. Tác giả gọi nó là "agent meta-harness". Theo cách tác giả giải thích, mô hình AI lo phần viết, còn harness cấp công cụ, bộ nhớ, vòng lặp và các giới hạn để mô hình làm việc được thật sự.
Repo này dành cho ai đã dùng Claude Code (hoặc Codex) và thấy một cuộc trò chuyện đơn lẻ chưa đủ cho việc lớn như rà soát cả repo, viết test, theo dõi chi phí. Lập trình viên mới và người làm văn phòng có thể dùng, miễn là chấp nhận mở terminal gõ một lệnh. Hiện repo có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.
Điểm đáng giá nhất là bạn không phải học hết. README nói rõ: sau khi chạy init, bạn cứ dùng Claude Code như bình thường, phần hook sẽ tự định tuyến tác vụ và điều phối agent ở nền. Bài này đi từ cài đặt, kiểm tra, đến vài tình huống dùng thật, kèm những giới hạn bạn nên biết trước.
ruvnet/ruflo
ruflo là bộ điều phối (harness) thêm agent, bộ nhớ, hook và MCP server cho Claude Code và Codex, cài bằng một lệnh npx.
I.ruflo làm được gì
Dưới đây là những phần chính, mình diễn giải theo lợi ích thay vì chép lại README.
- Thêm đội agent vào Claude Code. Chế độ cài đầy đủ đưa vào dự án 98 agent, hơn 60 lệnh và 30 skill (theo bảng so sánh trong README). Bạn không cần tự viết từng agent "người review", "người viết test".
- Swarm: nhiều agent làm việc như một nhóm. Bạn có thể yêu cầu Claude dùng một swarm để rà soát repo, tìm module rủi ro nhất, viết test và tóm tắt thay đổi. Việc chia nhỏ và phối hợp do ruflo lo.
- Bộ nhớ qua các phiên. README mô tả bộ nhớ tự học và nhớ giữa các lần làm việc, dùng tìm kiếm vector. Lợi ích thực tế: đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code. README có ghi chú rằng phần học này vẫn cần embedding và các module học được cấu hình.
- MCP server. ruflo chạy như một MCP server, nên Codex hoặc các ứng dụng hỗ trợ MCP khác cũng dùng được.
- Bảng điều khiển (console) trong Claude Code. Bạn theo dõi workflow, agent, model, token và chi phí ngay cạnh Claude Code, mở bằng lệnh
/ruflo. Có thể xem log từng lần chạy, tìm kiếm, xem lỗi, phát lại và so sánh. - Kho plugin lớn. README liệt kê 48 plugin, chia nhóm: điều phối, bộ nhớ, học và suy luận, kiểm thử, bảo mật, DevOps, mở rộng. Ví dụ
ruflo-testgentìm test còn thiếu và sinh test,ruflo-cost-trackertheo dõi token và cảnh báo ngân sách,ruflo-security-auditquét lỗ hổng. - Giới hạn quyền cho Claude khi điều khiển console. Bạn chọn mức
read,write,managehoặcfull, kèm chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các thao tác mạng, tốn tiền hay phá huỷ vẫn phải xác nhận kể cả khi đangauto. - Liên kết giữa nhiều máy (federation). Agent trên các máy khác nhau có thể trao đổi 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ì
Theo tư liệu của repo, bạn cần:
- Node.js từ phiên bản 20.0.0 trở lên.
package.jsonghi yêu cầu này. Lệnhnpxđi kèm Node. - Claude Code nếu bạn dùng cách cài vào dự án hoặc cách plugin. Riêng cách plugin cần Claude Code 2.1.287 trở lên. Lệnh cài plugin từ terminal (
claude plugin install ...) cần 2.1.292 trở lên. - Một dự án (thư mục) để cài vào. Lệnh
initchạy trong thư mục dự án của bạn. - Codex hoặc ứng dụng MCP khác nếu bạn không dùng Claude Code. Khi đó bạn chỉ cần trỏ nó tới ruflo.
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 cho ruflo. Bạn dùng tài khoản và key của chính Claude Code hoặc Codex như bình thường. Mục "Chưa rõ" trong phần hỏi đáp cũng nhắc lại điều này.
Các mod của ruflo chạy với 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. Hãy thử trên một dự án nháp trước, đừng thử ngay trên repo quan trọng.
III.Cài đặt từng bước
Có ba đường: cài đầy đủ vào dự án (khuyên dùng), cài chỉ plugin, hoặc chỉ cắm MCP. Mình hướng dẫn đường đầu tiên và nêu hai đường còn lại.
- Mở terminal đúng thư mụcVào thư mục dự án bạn muốn dùng ruflo
- Chạy initMột lệnh npx để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude CodeMở trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc thậtDùng câu lệnh mẫu của README
- Mở consoleGõ /ruflo để xem bảng điều khiển
A.Mở terminal trong thư mục dự án
Bạn cần đứng trong thư mục dự án, vì init ghi file vào đó (README nói sẽ có .claude/, .claude-flow/, CLAUDE.md, các file hỗ trợ và settings). Chưa có dự án thì tạo thư mục thử trước. Trên Windows bạn có thể mở PowerShell rồi dùng cd.
cd duong-dan-toi-du-an-cua-banĐổi duong-dan-toi-du-an-cua-ban thành đường dẫn thật. Lỗi hay gặp ở bước này là chạy lệnh ở sai thư mục, nên file bị ghi vào chỗ không mong muốn.
B.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initnpx tải và chạy ruflo mà không cần cài toàn cục. @latest lấy bản mới nhất. Lệnh sẽ thêm agent, hook, bộ nhớ và MCP server vào dự án. Lần đầu có thể mất một lúc vì phải tải gói.
Nếu muốn thiết lập có hỏi đáp từng bước, README ghi:
npx ruflo@latest init wizardNếu muốn xem trước, README có nhắc cờ --dry-run cho bản Grok (npx ruflo init --grok), nhưng không nói cờ này có dùng được cho lệnh init thường hay không. Bạn nên xem tài liệu trong repo trước khi thử.
C.Mở lại Claude Code
Mở Claude Code trong 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 thì hãy thoát ra mở lại.
D.Giao thử một việc
Dán câu mẫu trong 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.Bạn có thể viết bằng tiếng Việt, nhưng README chỉ ghi câu tiếng Anh này làm ví dụ.
E.Cách khác: chỉ cài plugin trong Claude Code
Cách này không thêm file nào vào dự án. Gõ từng dòng 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
/rufloTừ terminal thường, với Claude Code 2.1.292 trở lên, README ghi:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý README nói rõ: cách plugin chỉ cho một phần (lệnh slash, vài skill, định nghĩa agent), không có hook. Muốn đầy đủ như tài liệu mô tả thì dùng init.
F.Cách khác: Codex hoặc ứng dụng MCP khác
Trỏ ứng dụng của bạn tới lệnh sau, cùng các tham số:
npx -y ruflo@latest mcp startNếu ứng dụng đòi tách command và arguments, README ghi command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Mỗi ứng dụng có chỗ khai báo MCP server khác nhau. README không hướng dẫn chi tiết cho từng ứng dụng, nên bạn xem tài liệu của ứng dụng đó.
IV.Kiểm tra đã chạy được chưa
Có vài dấu hiệu theo tư liệu:
- Sau
init, thư mục dự án có thêm.claude/,.claude-flow/vàCLAUDE.md. - Mở lại Claude Code rồi gõ
/ruflo. Bảng điều khiển hiện ra là cài thành công. - Với cách plugin, gõ
/pluginvà kiểm tra các mod xuất hiện trong dòng active mods. - Muốn thử ngoài Claude Code, chạy bảng điều khiển trong terminal:
npx ruflo tuiThêm --plain để in ra một khung hình duy nhất, tiện cho script:
npx ruflo tui --plainREADME không đưa ra mẫu kết quả cụ thể cho lệnh này. Nếu terminal không báo lỗi và hiện giao diện, coi như chạy được.
V.Dùng vào việc thật
A.Rà soát một repo và viết test cho chỗ yếu nhất
Bạn là lập trình viên nhận lại dự án cũ, không biết chỗ nào dễ hỏng. Chạy npx ruflo@latest init trong dự án, mở Claude Code rồi dán câu mẫu của README (Use a ruflo swarm to review this repo...). Mong đợi theo README: swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Hãy đọc kỹ phần tóm tắt và chạy test trước khi nhận thay đổi.
Đừng học hết 406 công cụ. Chạy init, rồi cứ dùng Claude Code như bình thường.
Ông T
B.Cho Claude tạo một mission, mình vẫn giữ quyền duyệt
Bạn muốn thử Claude điều khiển bảng console mà không sợ nó làm bậy. README hướng dẫn:
- Cài console, mở
/ruflo, vào Settings → Claude control và chọn write + ask. - Nhờ Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status."
- Claude mở mục Missions và đặt mục tiêu. Bạn xác nhận thao tác tạo đang chờ.
- Kiểm tra mục Missions có mục tiêu và Overview ghi lại hành động.
Lưu ý README nhấn mạnh: tạo mission không có nghĩa tính năng đã được viết. Bấm Take back control bất cứ lúc nào để dừng Claude điều khiển.
C.Dùng ruflo từ Codex hoặc công cụ MCP khác
Bạn dùng Codex hơn Claude Code. Bạn khai báo MCP server với command npx và arguments -y ruflo@latest mcp start như phần cài đặt ở trên. Sau đó công cụ của ruflo (bộ nhớ, swarm, agent) có thể được gọi từ chính ứng dụng đó. README không mô tả kịch bản chi tiết cho Codex, nên bạn nên thử trên dự án nhỏ trước.
D.Theo dõi chi phí và tạo test bằng plugin lẻ
Bạn không muốn cài cả bộ vào dự án, chỉ muốn thử một món. Dùng cách plugin: thêm marketplace bằng /plugin marketplace add ruvnet/ruflo, rồi cài thứ bạn cần, chẳng hạn ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí) hoặc ruflo-testgen (tìm test còn thiếu và sinh test). README ghi mẫu lệnh cài cho ruflo-core, ruflo-swarm, ruflo-rag-memory, nên với plugin khác bạn làm tương tự: /plugin install tên-plugin@ruflo, rồi /reload-plugins.
VI.Lỗi hay gặp và cách xử lý
Lệnh /plugin hoặc /ruflo không nhận. Rất có thể Claude Code của bạn cũ. Cách plugin cần 2.1.287 trở lên, lệnh claude plugin install cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi chạy /reload-plugins hoặc mở lại.
npx báo lỗi hoặc không chạy. package.json yêu cầu Node 20 trở lên. Kiểm tra phiên bản bằng node --version và nâng cấp nếu thấp hơn.
Đã chạy init mà Claude Code không thấy agent hay công cụ mới. README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy thoát hẳn rồi mở lại, và đảm bảo bạn mở đúng thư mục đã chạy init.
Plugin bị nạp hai lần. Với các plugin bên ngoài như agentic-qe-fleet, agentdb, agentic-flow, README cảnh báo chỉ cài từ một marketplace, vì cài từ cả hai thì mod và lệnh sẽ nạp đôi.
Tên công cụ MCP khác với tài liệu. Cách plugin đăng ký công cụ dạng mcp__plugin_ruflo-core_ruflo__memory_store, trong khi cách cài bằng CLI dùng tên trần như memory_store. Nếu làm theo hướng dẫn mà gọi sai tên, hãy kiểm tra bạn đang dùng cách cài nào.
Claude từ chối một thao tác trong console. Thao tác vượt mức quyền bạn đã cấp sẽ bị từ chối. Đó là thiết kế an toàn, không phải lỗi. Nếu thật sự cần, hãy tự nâng mức quyền trong Settings, nhưng nên nhớ mặc định hiện là read + ask.
VII.Có nên dùng không
Điểm mạnh. Cài chỉ một lệnh. Có sẵn rất nhiều agent, plugin và console theo dõi chi phí. Có giới hạn quyền rõ ràng khi cho Claude điều khiển. Hỗ trợ cả Claude Code, Codex và các ứng dụng MCP. Giấy phép MIT và repo còn hoạt động.
Giới hạn. Repo rất lớn (hàng trăm công cụ MCP, hàng chục lệnh, 48 plugin), nên người mới dễ choáng. README cũng thừa nhận một số hình minh hoạ dùng dữ liệu mẫu, không chứng minh swarm hay bộ nhớ đã làm xong việc thật. Phần học tự động vẫn cần embedding và module được cấu hình. Các mod chạy với quyền tài khoản của bạn và không được cô lập. Tài liệu chưa nói gì về chi phí token khi chạy nhiều agent, nên bạn hãy tự theo dõi.
Khi nào chọn cách khác. Nếu bạn chỉ cần trợ lý trả lời và sửa code một file vài lần mỗi tuần, Claude Code đơn thuần là đủ. Nếu chỉ cần một tính năng nhỏ (ví dụ theo dõi chi phí), hãy cài đúng một plugin thay vì cả bộ. Nếu bạn lo về chuyện file bị ghi vào dự án, dùng cách plugin (không thêm file) hoặc thử trên bản sao trước.
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 code tự do. Tư liệu không nói gì về chi phí khi chạy agent. Bạn vẫn trả phí cho dịch vụ AI bên dưới (như Claude Code hoặc Codex) theo gói của chính bạn.
ruflo khác gì Claude Code?
Claude Code là công cụ AI lập trình. ruflo là lớp điều phối đặt quanh nó (và Codex), thêm agent chuyên biệt, swarm, bộ nhớ, hook và bảng điều khiển. Bạn vẫn làm việc trong Claude Code, ruflo thêm các khả năng này vào.
Cần cài những gì để chạy ruflo?
Theo tư liệu, bạn cần Node.js 20 trở lên và Claude Code (hoặc Codex hay ứng dụng MCP khác). Với cách plugin cần Claude Code từ 2.1.287 trở lên. README không nói gì về yêu cầu GPU hay phần cứng riêng.
Cài ruflo có làm thay đổi dự án của tôi không?
Có, nếu dùng npx ruflo@latest init: README nói lệnh này thêm .claude/, .claude-flow/, CLAUDE.md và các file hỗ trợ vào dự án. Nếu không muốn thêm file nào, dùng cách chỉ cài plugin trong Claude Code, cách này không đặt file vào workspace.
Có chạy được trên Windows không?
Tư liệu không nêu rõ danh sách hệ điều hành được hỗ trợ. Điều có thể chắc chắn là gói cần Node 20 trở lên và chạy bằng npx. Bạn nên thử trên dự án nháp để kiểm tra.
Dùng ruflo có an toàn không?
README nói các mod chạy với quyền tài khoản của bạn và không bị sandbox, nên cần đọc code trước khi cài. Khi cho Claude điều khiển console, mặc định hiện là read + ask, và các thao tác mạng, tốn tiền, phá huỷ vẫn phải xác nhận. Tư liệu không cho biết thêm về cách dữ liệu được lưu hay gửi đi.
Dùng ruflo với Codex được không?
Được. README ghi Codex và các ứng dụng MCP khác dùng được bằng cách trỏ tới lệnh npx -y ruflo@latest mcp start, hoặc chạy npx ruflo@latest init wizard để thiết lập dự án có hỏi đáp. Chi tiết cấu hình theo từng ứng dụng thì README chưa nói.


