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 là một agent harness (lớp điều phối) cho Claude Code và Codex, giúp nhiều agent phối hợp thành nhóm, nhớ việc qua các phiên và có bảng điều khiển để theo dõi. Cài bằng một lệnh npx trong thư mục dự án, cần Node 20 trở lên. Người mới làm được, nhưng nên bắt đầu với một việc nhỏ để làm quen.
Ruflo là một “agent harness” mã nguồn mở: lớp công cụ bọc quanh Claude Code và Codex để AI không chỉ trả lời từng câu, mà làm việc theo nhóm, có bộ nhớ và có kiểm soát. Repo ban đầu tên Claude Flow, sau đổi thành Ruflo, viết chủ yếu bằng TypeScript, giấy phép MIT, hiện có khoảng 81.582 sao và 9.607 fork.
Tác giả mô tả theo kiểu: model là người viết, còn harness là bàn làm việc xung quanh, gồm công cụ, bộ nhớ, vòng lặp và các giới hạn an toàn. Ruflo đóng vai bàn làm việc đó. Sau khi chạy init, Claude Code được thêm hơn 100 agent chuyên biệt, hook tự định tuyến công việc, bộ nhớ qua các phiên và một MCP server.
Bài này hợp với bạn nếu đã dùng Claude Code hoặc Codex và muốn giao những việc dài hơi hơn, như rà soát cả repo, viết test, theo dõi chi phí. Điểm đáng giá nhất: README nói rõ bạn không cần học hết hàng trăm công cụ bên trong. Cài xong, bạn cứ dùng Claude Code như bình thường, phần còn lại chạy nền.
ruvnet/ruflo
Ruflo là lớp điều phối bọc quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server chỉ bằng một lệnh npx ruflo@latest init.
I.Ruflo làm được gì
Repo rất lớn, nên mình chỉ nêu những phần bạn dễ dùng nhất.
- Swarm (đàn agent phối hợp). Thay vì một AI làm mọi thứ, nhiều agent chia việc cho nhau. Bạn chỉ cần nhờ Claude Code “dùng một swarm của ruflo” để làm việc. Lợi ích là các việc lớn như rà soát cả kho mã được chia nhỏ và làm song song.
- Hook tự định tuyến. Sau
init, hook sẽ tự chuyển nhiệm vụ cho agent phù hợp và học từ những lần thành công. Bạn không phải chọn agent bằng tay. - Bộ nhớ qua các phiên. Agent nhớ được kinh nghiệm giữa các lần làm việc, thay vì mỗi lần bắt đầu từ con số không. README ghi phần truy xuất vector cục bộ có thể chạy mà không cần LLM, nhưng vẫn cần embedding và các module học đã cấu hình.
- MCP server. Ruflo chạy như một MCP server, nên Codex hoặc client MCP khác cũng kết nối được.
- Bảng điều khiển trong Claude Code (
/ruflo). Bạn xem workflow, agent, model, token và chi phí ngay cạnh Claude Code. Bạn còn mở được log từng lần chạy, tìm kiếm, xem lỗi, phát lại và so sánh. - Cho Claude điều khiển bảng điều khiển, nhưng có giới hạn. Trong Settings có mục Claude control với bốn mức
read,write,manage,full, và hai kiểu 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ỷ vẫn phải xác nhận kể cả khi đểauto. - 48 plugin cài lẻ. Có plugin cho swarm, bộ nhớ RAG, sinh test (
ruflo-testgen), theo dõi chi phí (ruflo-cost-tracker), quét bảo mật (ruflo-security-audit), chặn prompt injection (ruflo-aidefence) và nhiều loại khác. Bạn chọn cái cần, không phải cài hết. - Federation. Agent trên các máy khác nhau có thể trao đổi với nhau một cách an toàn. Đây là phần nâng cao, người mới có thể bỏ qua lúc đầu.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js từ 20.0.0 trở lên. Đây là yêu cầu trong
package.json. Lệnhnpxđi kèm Node. - Claude Code nếu bạn dùng đường cài vào dự án. Với đường chỉ cài plugin, README yêu cầu Claude Code từ 2.1.287 trở lên. Lệnh cài plugin từ terminal cần từ 2.1.292 trở lên.
- Codex hoặc client MCP khác nếu bạn không dùng Claude Code. Chỉ cần trỏ nó tới ruflo như hướng dẫn ở dưới.
- Một thư mục dự án để chạy lệnh
init.
Tư liệu không nêu yêu cầu về hệ điều hành, GPU hay dung lượng ổ đĩa. Nếu bạn quan tâm, hãy xem thêm trong README.md và thư mục docs/ của 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ị đóng khung sandbox. README khuyên đọc mã trước khi cài. Hãy thử trong một thư mục dự án nhỏ trước, đừng thử đầu tiên trên dự án quan trọng.
III.Cài đặt từng bước
README có ba đường: cài vào dự án (đầy đủ nhất), chỉ cài plugin trong Claude Code, và dùng với Codex hoặc client MCP. Bạn chỉ cần chọn một.
- Mở terminalVào đúng thư mục dự án của bạn
- Chạy initGõ npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Khởi động lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việcDán câu lệnh mẫu để chạy swarm
- (Tuỳ chọn) Mở bảng điều khiểnGõ /ruflo trong Claude Code
A.Mở terminal đúng thư mục
Lỗi người mới hay gặp nhất là chạy lệnh sai chỗ. init thêm tệp vào thư mục hiện tại, nên bạn cần mở terminal ngay trong thư mục dự án. Trên Windows, bạn có thể dùng PowerShell. Ví dụ:
cd duong-dan-toi-du-an-cua-banHãy thay duong-dan-toi-du-an-cua-ban bằng đường dẫn thật tới thư mục dự án của bạn.
B.Chạy lệnh init
Đây là lệnh chính của README:
npx ruflo@latest initLệnh này tải ruflo về tạm thời qua npx rồi cài vào dự án các agent, hook, bộ nhớ và MCP server. Theo bảng so sánh trong README, đường này tạo thêm .claude/, .claude-flow/, CLAUDE.md và một số tệp phụ trợ trong dự án. Nếu dự án đã có CLAUDE.md, bạn nên sao lưu hoặc dùng Git để so sánh trước khi chạy.
Nếu muốn thiết lập từng bước theo kiểu hỏi đáp, README có lệnh:
npx ruflo@latest init wizardC.Khởi động lại Claude Code
Mở Claude Code trong cùng thư mục. README ghi Claude Code sẽ nhận agent, hook và MCP server ở lần khởi động kế tiếp. Nếu bạn đang để Claude Code mở sẵn, hãy thoát rồi mở lại.
D.Đường thay thế: chỉ cài plugin trong Claude Code
Đường này không thêm tệp nào vào dự án, nhưng chỉ có phần công cụ cơ bản, bảng điều khiển và mod. Gõ các lệnh sau bên trong Claude Code (không phải trong 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
/rufloNếu bạn dùng Claude Code từ 2.1.292 trở lên, README cũng cho phép cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloNhớ rằng đường plugin mỏng hơn. README ghi rõ nó không cài hook, và chỉ ruflo-core mới đăng ký MCP server riêng. Muốn đủ bộ “vòng lặp ruflo”, bạn dùng npx ruflo@latest init.
E.Đường thay thế: Codex hoặc client MCP khác
Bạn cấu hình client với command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Tức là client sẽ chạy npx -y ruflo@latest mcp start. Cách điền cụ thể tuỳ từng client, nên bạn cần xem tài liệu của client đó.
F.Chạy bảng điều khiển ngoài Claude Code
Nếu chỉ muốn xem giao diện terminal mà không dùng Claude Code:
npx ruflo tuiThêm --plain để in ra một khung hình, 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, nên bạn kiểm tra theo các dấu hiệu sau:
- Sau
init: trong thư mục dự án xuất hiện.claude/,.claude-flow/vàCLAUDE.md. Đây là các tệp README liệt kê cho đường cài này. - Trong Claude Code: khởi động lại, rồi gõ
/ruflo. Nếu bảng điều khiển hiện ra, hệ thống đã nhận. - Với plugin: gõ
/pluginvà kiểm tra các mod đã cài có nằm trong dòng “active mods” hay không. README hướng dẫn kiểm tra theo cách này. - Thử một việc thật: giao cho Claude Code một nhiệm vụ nhỏ (xem phần dưới) và quan sát agent có được điều phối không.
Nếu một trong các bước trên không có kết quả, hãy xem phần lỗi thường gặp ở dưới.
V.Dùng vào việc thật
Mình bám đúng các ví dụ và khả năng README mô tả.
A.Dev cần rà soát một repo lạ
Bạn vừa nhận một dự án từ đồng nghiệp và chưa biết chỗ nào dễ hỏng. Sau khi chạy init và mở lại Claude Code, bạn dán đúng 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.Yêu cầu này gồm ba việc: tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Kết quả mong đợi là một bản tóm tắt cùng các tệp test mới. Bạn nên đọc lại và chạy test trước khi giữ lại.
Cứ dùng Claude Code như bình thường, phần điều phối để ruflo lo ở nền.
Ông T
B.Người không rành code muốn xem AI đang làm gì
Bạn giao việc cho Claude Code nhưng không biết nó đang tốn bao nhiêu token hay đang làm tới đâu. Gõ /ruflo để mở bảng điều khiển. Ở đây bạn xem được workflow, agent, model, token và chi phí. Khi có việc lỗi, bạn mở log và kết quả của lần chạy để xem chuyện gì xảy ra, rồi phát lại hoặc so sánh các lần chạy.
C.Tạo một “mission” có kiểm soát
README có một kịch bản thử an toàn. Bạn vào Settings, mục Claude control, chọn write + ask. Sau đó 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 đang chờ. Cuối cùng, bạn kiểm tra Missions đã có mục tiêu, và Overview đã ghi lại hành động. README nhắc rõ: tạo mission không có nghĩa là tính năng đã được làm xong. Nếu cần dừng, bấm Take back control.
D.Dự án nhóm cần theo dõi chi phí và bảo mật
Nếu bạn dùng đường plugin, có thể cài thêm từng plugin lẻ. README liệt kê ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí), ruflo-security-audit (quét lỗ hổng và CVE) và ruflo-testgen (tìm test còn thiếu rồi tạo). Ví dụ cài theo đúng cú pháp README:
/plugin install ruflo-cost-tracker@rufloBạn nên cài từng plugin một và thử trước khi cài tiếp, để biết cái nào thực sự có ích cho mình.
VI.Lỗi hay gặp và cách xử lý
Chạy npx báo lỗi vì Node quá cũ. Repo yêu cầu Node 20.0.0 trở lên. Hãy kiểm tra phiên bản bằng node --version, rồi nâng cấp Node nếu cần.
Mở Claude Code nhưng không thấy gì mới. Nguyên nhân thường là bạn mở Claude Code ở sai thư mục, hoặc chưa khởi động lại sau init. Hãy thoát hẳn, vào lại đúng thư mục đã chạy init rồi mở lại.
Lệnh /plugin không nhận. Đường plugin cần Claude Code từ 2.1.287 trở lên. Hãy cập nhật Claude Code, sau đó gõ /reload-plugins để nạp lại.
Cài một plugin từ hai nguồn nên bị lặp. README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow: nên cài từ một marketplace thôi, vì cài từ cả hai nơi thì mod và lệnh sẽ nạp hai lần. Nếu thấy lặp, hãy gỡ một nơi.
Claude bị từ chối khi điều khiển bảng điều khiển. Đây là thiết kế chứ không phải lỗi. Mức mặc định là read + ask, và hành động vượt quyền sẽ bị từ chối. Nếu muốn Claude tạo hoặc sửa, bạn tự nâng mức lên (ví dụ write) và nhớ rằng bạn có thể bấm Take back control bất cứ lúc nào.
Với các lỗi khác, bạn xem CHANGELOG.md, thư mục docs/ hoặc mục Issues của repo, vì tư liệu mình có chưa liệt kê hết.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Có đường nhẹ (plugin, không thêm tệp vào dự án) và đường đầy đủ. Bảng điều khiển giúp bạn nhìn thấy agent và chi phí. Phần quyền Claude control thiết kế khá thận trọng. Giấy phép MIT, và repo vẫn được cập nhật trong vài tháng gần đây.
Giới hạn. Repo rất lớn: README nhắc tới hàng trăm công cụ MCP, hàng chục lệnh CLI và 48 plugin, nên dễ bị ngợp. Đường init thêm khá nhiều tệp vào dự án. Mod chạy với quyền tài khoản của bạn, không có sandbox. README cũng nói các ảnh động trong tài liệu dùng dữ liệu mẫu, và không phải bằng chứng cho việc swarm hoàn thành công việc thật hay bộ nhớ nhớ được. Nghĩa là bạn nên tự thử trên việc của mình rồi mới tin.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code hỏi đáp, sửa vài tệp nhỏ, bạn chưa cần lớp điều phối này. Nếu cần một công cụ nhỏ và dễ hiểu cho một việc duy nhất, hãy tìm một plugin hoặc MCP server chuyên dụng. Còn nếu bạn hay giao việc dài, lặp đi lặp lại và muốn theo dõi chi phí, 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 dùng giấy phép MIT, nên bạn dùng và sửa tự do. Tuy nhiên Ruflo chạy cùng Claude Code, Codex hoặc các nhà cung cấp AI khác, nên chi phí của các dịch vụ đó vẫn tính riêng. Tư liệu không nêu bảng giá cụ thể.
Ruflo có cần GPU không?
Tư liệu mình có không nói Ruflo bắt buộc GPU. Một plugin trong danh sách (ruflo-ruvector) có nhắc tìm kiếm tăng tốc bằng GPU, nhưng đó chỉ là plugin tuỳ chọn. Yêu cầu bắt buộc duy nhất được ghi là Node 20.0.0 trở lên.
Cài Ruflo bằng lệnh nào?
Lệnh chính là npx ruflo@latest init, chạy trong thư mục dự án của bạn. Sau đó mở lại Claude Code trong cùng thư mục. Nếu không muốn thêm tệp vào dự án, bạn có thể cài plugin bằng lệnh /plugin ngay trong Claude Code.
Ruflo dùng được với Codex hay chỉ có Claude Code?
Dùng được cả hai. Với Codex hoặc client MCP khác, bạn cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Cách điền cụ thể tuỳ từng client.
Ruflo có chạy được trên Windows không?
Tư liệu mình có không nói rõ hệ điều hành nào được hỗ trợ. Vì cài bằng npx với Node 20 trở lên nên về nguyên tắc bạn có thể thử, nhưng chưa có thông tin chính thức. Bạn nên xem README và mục Issues của repo.
Cho Claude điều khiển bảng điều khiển có an toàn không?
README thiết kế khá thận trọng: mặc định chỉ đọc và hỏi lại trước khi làm. Các hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả khi để chế độ auto. Bạn cũng có thể bấm Take back control để dừng ngay. Riêng mod thì chạy với quyền tài khoản của bạn và không có sandbox, nên cần đọc mã trước khi cài.
Ruflo khác gì dùng Claude Code thuần?
Claude Code thuần là một agent làm việc đơn lẻ. Ruflo bọc thêm lớp điều phối: nhiều agent chuyên biệt, hook tự định tuyến, bộ nhớ giữa các phiên, bảng điều khiển và các plugin. README mô tả Ruflo là lớp thực thi bọc quanh Claude Code và Codex, nên nó bổ sung chứ không thay thế.


