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 agent harness: lớp công cụ bao quanh Claude Code và Codex để chạy nhiều agent phối hợp, có bộ nhớ qua các phiên làm việc. Cài chỉ cần một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node từ 20 trở lên. Sau đó bạn cứ dùng Claude Code bình thường.
Ruflo là một "agent harness" — lớp công cụ đặt quanh Claude Code và Codex để các AI agent không chỉ chạy lẻ tẻ mà biết phối hợp thành đội, nhớ việc đã làm và có giới hạn an toàn. Repo này trước đây tên Claude Flow, hiện hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, dùng giấy phép MIT.
Nếu bạn đã dùng Claude Code và thấy nó hay quên ngữ cảnh giữa các phiên, hoặc muốn giao một việc lớn cho nhiều agent cùng làm, thì Ruflo dành cho bạn. Tác giả mô tả ngắn gọn: mô hình AI là người viết, còn harness là bàn làm việc gồm công cụ, bộ nhớ, vòng lặp và các điều khiển để mô hình làm việc được thật.
Điểm đáng giá nhất là cách cài rất gọn: một lệnh npx ruflo@latest init trong thư mục dự án, rồi mở Claude Code như thường. README nói rõ 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; sau khi init, hệ thống hook tự định tuyến tác vụ và điều phối agent ở phía sau.
ruvnet/ruflo
Ruflo là bộ khung (harness) thêm agent, bộ nhớ, hook và MCP server cho Claude Code và Codex, cài bằng một lệnh npx trong thư mục dự án.
I.Ruflo làm được gì
Dưới đây là những phần chính, theo cách hiểu thực tế cho người mới.
- Đội agent (swarm): README nói Ruflo bổ sung hơn 100 agent chuyên biệt và cho chúng tự tổ chức thành nhóm. Lợi ích: một việc lớn như rà soát cả repo có thể chia cho nhiều agent thay vì một agent làm tuần tự.
- Bộ nhớ qua nhiều phiên: agent nhớ được kinh nghiệm từ các tác vụ trước. Bạn đỡ phải giải thích lại bối cảnh mỗi lần mở Claude Code.
- Hook tự định tuyến: sau
init, bạn dùng Claude Code bình thường, còn hook tự chọn cách xử lý và học từ các mẫu làm việc thành công. - MCP server: Ruflo đi kèm một MCP server, nên Codex hoặc các MCP client khác cũng kết nối được.
- Bảng điều khiển (console): một "buồng lái" cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí, xem log, tìm lỗi, phát lại và so sánh các lần chạy. Mở bằng lệnh
/ruflotrong Claude Code. - Claude điều khiển console có giới hạn: bạn chọn mức quyền
read,write,managehoặcfull, và 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á hủy luôn cần xác nhận, kể cả ở chế độauto. - Hệ plugin: README liệt kê 48 plugin (cộng 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học máy, chất lượng mã và kiểm thử, bảo mật, kiến trúc, DevOps, mở rộng. Ví dụ
ruflo-testgentìm test còn thiếu và tạo test,ruflo-cost-trackertheo dõi token và cảnh báo chi phí,ruflo-security-auditquét lỗ hổng. - 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. Đây là tính năng nâng cao, người mới chưa cần đụng tới.
Trong số đó, phần bạn nên thử trước là đội agent, bộ nhớ và console. Còn lại cứ để đó khi cần mới tìm hiểu.
II.Cần chuẩn bị gì
Theo tư liệu repo, bạn cần:
- Node.js từ phiên bản 20.0.0 trở lên (package.json yêu cầu
>=20.0.0). Cần cónpxđi kèm Node. - Claude Code nếu bạn muốn dùng đường cài chính. Riêng đường cài chỉ bằng plugin cần Claude Code 2.1.287 trở lên; lệnh cài plugin từ terminal cần 2.1.292 trở lên.
- Một thư mục dự án để chạy
init(lệnh này thêm file vào dự án). - Tài khoản và API key cho Claude Code hoặc Codex: tư liệu ở đây chưa nói chi tiết, bạn dùng theo cách bạn đang dùng các công cụ đó.
README phần đã cung cấp chưa nêu rõ hệ điều hành hỗ trợ hay yêu cầu phần cứng như GPU. Cần chắc chắn thì xem tiếp README và thư mục docs/ trong repo.
III.Cài đặt từng bước
Có ba đường cài. Đường chính nhanh nhất là init; hai đường còn lại dành cho trường hợp đặc biệt.
- Mở terminal trong dự ánVào đúng thư mục dự án bạn muốn dùng Ruflo
- 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ệc thậtDán câu lệnh mẫu để Claude dùng swarm
- (Tuỳ chọn) Mở consoleGõ /ruflo trong Claude Code
A.Mở terminal đúng thư mục
Lệnh init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng dự án. Chỗ này người mới hay vấp: mở terminal ở thư mục khác thì Ruflo sẽ cài sai chỗ.
cd duong-dan-toi-du-an-cua-banĐây chỉ là lệnh cd thông thường. Hãy thay phần sau cd bằng đường dẫn thật của dự án 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 Ruflo bản mới nhất mà không cần cài toàn cục. README cho biết init thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Phần so sánh trong README nói đường này tạo các file như .claude/, .claude-flow/, CLAUDE.md cùng một số file hỗ trợ và settings. Vì vậy nếu dự án nằm trong git, bạn nên commit trước để dễ xem Ruflo đã thêm gì.
Nếu muốn thiết lập theo kiểu hỏi đáp từng bước, README có lệnh:
npx ruflo@latest init wizardC.Khởi động lại Claude Code và giao việc
Mở (hoặc mở lại) 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. Rồi thử một câu như README gợi ý:
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ờ Claude dùng một swarm để rà soát repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi.
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 và cần Claude Code 2.1.287 trở lên. Gõ từng dòng 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
/rufloNếu dùng Claude Code 2.1.292 trở lên, bạn cũng có thể cài từ terminal:
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à README nói chúng không được cách ly (sandbox). Hãy đọc mã nguồn trước khi cài.
README cũng nói đường plugin chỉ cho lệnh slash và vài skill, không có hook; muốn dùng đầy đủ như tài liệu mô tả thì chọn đường init.
E.Cách khác: Codex hoặc MCP client khác
Không cần cài vào dự án. Trong phần cấu hình MCP của công cụ, đặt command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]Nghĩa là công cụ của bạn sẽ chạy npx -y ruflo@latest mcp start để khởi động MCP server của Ruflo.
F.Chạy giao diện terminal riêng
Console cũng chạy độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain để in một khung hình duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Theo README, có vài dấu hiệu:
- Sau
initvà khởi động lại Claude Code, thư mục dự án xuất hiện các file/thư mục mới như.claude/và.claude-flow/. - Gõ
/ruflotrong Claude Code sẽ mở console (nếu bạn đã càiruflo-console). - Với đường plugin, mở
/pluginvà xem plugin có hiện trong dòng "active mods" không. - Có thể chạy
npx ruflo tuiđể thấy console chạy riêng trong terminal. - Thử bài "tạo mission" trong README: vào Settings → Claude control → write + ask, rồi nhờ Claude "Create a mission to add a dark mode toggle. Show me the mission and its status." Xác nhận hành động tạo, rồi kiểm tra mục Missions và Overview. Lưu ý: tạo mission không có nghĩa là tính năng đã được viết xong.
README chưa nêu một dòng "thành công" cố định cho lệnh init, nên cách chắc nhất là kiểm tra các dấu hiệu trên.
V.Dùng vào việc thật
Tư liệu cho thấy Ruflo mạnh nhất ở việc điều phối nhiều bước. Dưới đây là các tình huống bám đúng khả năng được mô tả.
A.Lập trình viên mới: rà soát dự án thừa kế
Bạn vừa nhận một dự án của người khác và không biết bắt đầu từ đâu. Sau khi init và mở lại Claude Code, dán 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ả mong đợi: Claude 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 tin.
Agent = Model + Harness: mô hình viết, còn harness cho nó công cụ, bộ nhớ và giới hạn để làm việc thật.
Ông T
B.Chủ dự án nhỏ: theo dõi chi phí và việc agent đang làm
Bạn giao việc cho agent nhưng sợ tốn token mà không biết. Cài ruflo-console rồi gõ /ruflo để xem workflow, agent, model, token và chi phí cạnh Claude Code. Bạn còn có thể cài ruflo-cost-tracker để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí.
/plugin install ruflo-cost-tracker@rufloKết quả: bạn thấy được mỗi lần chạy tốn bao nhiêu và lần nào lỗi, thay vì chờ hóa đơn cuối tháng.
C.Nhân viên kỹ thuật: bổ sung test còn thiếu
Công ty có mã nguồn nhưng ít test. Plugin ruflo-testgen theo README tìm test còn thiếu và tạo chúng tự động.
/plugin install ruflo-testgen@rufloSau đó nhờ Claude nêu rõ thư mục cần kiểm tra. Kết quả là một bộ test nháp để bạn xem lại, không phải bản cuối cùng.
D.Người dùng Codex: gắn Ruflo như một MCP server
Bạn không dùng Claude Code mà dùng Codex. Thêm một MCP server với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"] như phần cài đặt ở trên. Khi đó công cụ của bạn gọi được các công cụ của Ruflo mà không phải thêm file vào dự án.
Hãy bắt đầu với mức quyền mặc định read + ask của console. Chỉ nâng lên write, manage hay full khi bạn đã hiểu Claude sẽ làm gì. Mọi hành động tốn tiền, đụng mạng hoặc phá hủy vẫn cần bạn xác nhận.
VI.Lỗi hay gặp và cách xử lý
Tư liệu không có mục xử lý lỗi riêng, nên dưới đây là các tình huống rất dễ gặp với loại công cụ này.
1. Lệnh npx báo lỗi hoặc không chạy. Thường do Node quá cũ. Kiểm tra bằng node --version; package.json yêu cầu từ 20.0.0 trở lên. Nếu thấp hơn, cập nhật Node rồi chạy lại.
2. Claude Code không thấy Ruflo sau init. README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy đóng hẳn Claude Code, mở lại trong đúng thư mục bạn vừa chạy init.
3. Lệnh /plugin không chạy hoặc báo phiên bản. Đườ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). Cập nhật Claude Code hoặc chuyển sang đường init. Sau khi cài plugin, nhớ gõ /reload-plugins.
4. Plugin cài rồi mà thiếu tính năng. Theo README, đường plugin chỉ cho lệnh slash, vài skill và định nghĩa agent; hook và hầu hết MCP server thì không có. Muốn đầy đủ, dùng npx ruflo@latest init.
5. Một plugin ngoài bị tải hai lần. README cảnh báo với agentic-qe-fleet, agentdb, agentic-flow: chỉ cài từ một marketplace duy nhất, vì cài từ cả hai thì mod và lệnh bị nạp hai lần.
6. Claude từ chối hành động trong console. Rất có thể mức quyền của bạn đang thấp hơn hành động đó. README nói hành động vượt mức quyền sẽ bị từ chối. Nâng mức quyền có chủ ý, hoặc bấm Take back control nếu muốn dừng.
VII.Có nên dùng không
Điểm mạnh:
- Cài nhanh, một lệnh, giấy phép MIT, repo còn được cập nhật trong 3 tháng gần đây.
- Gộp nhiều thứ vào một chỗ: agent, bộ nhớ, hook, MCP server, console theo dõi chi phí.
- Có cơ chế kiểm soát rõ ràng: mức quyền, chế độ duyệt, nút lấy lại quyền điều khiển.
- Dùng được với Claude Code, Codex và các MCP client khác.
Giới hạn cần biết:
- Bề mặt rất rộng (hàng chục plugin, hàng trăm công cụ). Người mới dễ choáng; hãy chỉ dùng vài thứ cần thiết.
initthêm nhiều file vào dự án. Hãy commit trước khi chạy để dễ hoàn tác.- Các mod không được sandbox và chạy với quyền tài khoản của bạn.
- README tự nói phần học và bộ nhớ ở mức "khái niệm", và một số bản demo dùng dữ liệu mẫu nên không chứng minh việc swarm đã hoàn thành. Hãy kiểm chứng kết quả thật.
- Thông tin về hệ điều hành, phần cứng, chi phí token chưa rõ trong tư liệu.
Khi nên chọn cách khác: nếu bạn chỉ cần Claude Code làm các việc đơn giản trong một file, dùng Claude Code thuần là đủ và nhẹ hơn. Ruflo đáng thử khi bạn có việc nhiều bước, muốn agent nhớ qua các phiên và muốn theo dõi chi phí tập trung. Bắt đầu bằng một dự án thử, đọc kỹ những gì init đã thêm, rồi mới mở rộng.
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 dùng được miễn phí. Tuy nhiên Ruflo chạy trên Claude Code, Codex hoặc nhà cung cấp mô hình khác, và chi phí đó tính riêng theo gói của bạn. Tư liệu chưa nêu mức chi phí cụ thể.
Cài Ruflo cần những gì?
Cần Node.js từ phiên bản 20.0.0 trở lên theo package.json. Đường cài chính là chạy `npx ruflo@latest init` trong thư mục dự án. Nếu chỉ cài plugin trong Claude Code thì cần Claude Code từ 2.1.287 trở lên.
Ruflo có cần GPU không?
Tư liệu cung cấp chưa nêu yêu cầu GPU cho đường cài cơ bản. README có nhắc một plugin riêng (ruflo-ruvector) liên quan tìm kiếm tăng tốc GPU, nhưng đó là tuỳ chọn. Bạn nên xem README đầy đủ nếu định dùng tính năng đó.
Ruflo chạy trên Windows được không?
README phần được cung cấp chưa ghi rõ hệ điều hành hỗ trợ. Lệnh chính là `npx` nên chạy được ở nơi có Node 20 trở lên, nhưng bạn nên xem README và thư mục docs/ trong repo để chắc chắn.
Ruflo khác gì dùng Claude Code thuần?
Ruflo bổ sung một lớp harness quanh Claude Code: hơn 100 agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook định tuyến và console theo dõi. Claude Code thuần không có sẵn các phần này. Đổi lại, Ruflo thêm nhiều file vào dự án và phức tạp hơn.
Dùng Ruflo có an toàn không, Claude có tự làm bậy được không?
Console cho bạn chọn mức quyền read, write, manage hoặc full và chế độ ask hoặc auto; mặc định hiện là read + ask. Hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần xác nhận kể cả ở chế độ auto. Riêng các mod không được sandbox và chạy với quyền tài khoản của bạn, nên cần đọc mã trước khi cài.
Tôi dùng Codex thì có dùng được Ruflo không?
Có. README nói Codex và các MCP client khác dùng được bằng cách cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Cách này không cần thêm file vào dự án.


