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 đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một «agent harness» mã nguồn mở: lớp công cụ bao quanh Claude Code và Codex để các agent AI không chỉ chạy một mình mà biết chia việc, nhớ lại kinh nghiệm và phối hợp với nhau. Repo này vốn tên là Claude Flow, do Reuven Cohen (rUv) tạo ra, viết chủ yếu bằng TypeScript, giấy phép MIT. Hiện có khoảng 81.600 sao và khoảng 9.600 fork trên GitHub.
Cách hiểu đơn giản nhất theo chính README: Agent = Model + Harness. Model (như Claude) là bộ não biết viết code. Harness là cái bàn làm việc xung quanh: công cụ, bộ nhớ, vòng lặp, giới hạn an toàn. Ruflo là phần bàn làm việc đó. Sau khi cài, Claude Code của bạn có thêm hàng chục agent chuyên biệt, hook tự động điều hướng tác vụ, và một MCP server để dùng các công cụ của Ruflo.
Bạn nên đọc bài này nếu bạn là lập trình viên (kể cả mới) đang dùng Claude Code hoặc Codex và muốn giao các việc lớn hơn như rà soát cả repo, viết test, ghi nhớ giữa các phiên. Điểm đáng giá nhất: chỉ một lệnh npx ruflo@latest init là xong phần cài, và README khuyên bạn cứ dùng Claude Code bình thường, không cần học hết hàng trăm công cụ.
ruvnet/ruflo
Ruflo là bộ khung bao quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, swarm phối hợp và MCP server chỉ với một lệnh npx.
I.Ruflo làm được gì
README giới thiệu rất nhiều thứ. Mình chọn những ý bạn dễ thấy lợi ích nhất.
- Agent chuyên biệt và swarm. Bạn có hơn 100 agent chuyên biệt (README ghi 98 agent ở đường cài bằng CLI). Chúng tự tổ chức thành «swarm», tức một nhóm cùng làm một việc. Lợi ích: một yêu cầu lớn được chia nhỏ thay vì dồn hết cho một cuộc hội thoại.
- Bộ nhớ qua các phiên. Agent nhớ được kinh nghiệm từ lần làm trước. README có nhắc bộ nhớ vector, tìm kiếm cục bộ và học từ tác vụ thành công. Lợi ích: 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ự động. Sau
init, hệ thống hook tự định tuyến tác vụ và phối hợp agent ở phía sau. Bạn không phải gõ lệnh riêng cho từng việc. - MCP server. Codex hoặc bất kỳ client MCP nào cũng nối được vào Ruflo, không chỉ riêng Claude Code.
- Bảng điều khiển (console). Một «buồng lái» đặt cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí; mở log từng lần chạy, tìm kiếm, xem lại và so sánh. Chạy được cả trong terminal thường với
npx ruflo tui. - Cho Claude điều khiển console, nhưng bạn đặt giới hạn. Có bốn mức quyền:
read,write,manage,full, kèm 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 bạn xác nhận, kể cả ở chế độauto. - Kho plugin. README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài): swarm, tạo test, quét bảo mật, theo dõi chi phí token, tìm kiếm RAG, tài liệu, v.v. Bạn cài cái nào cần.
- 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. Với người mới, phần này chưa cần đụng tới.
II.Cần chuẩn bị gì
Tư liệu của repo chỉ nêu một số yêu cầu rõ ràng:
- Node.js từ 20.0.0 trở lên.
package.jsonyêu cầu như vậy, và lệnh cài dùngnpxđi kèm Node. - Claude Code nếu bạn dùng theo cách chính. Riêng đường cài chỉ bằng plugin, README yêu cầu 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
inittrong đó. - Codex hoặc client MCP khác là tuỳ chọn, nếu bạn không dùng Claude Code.
README phần mình có không nói rõ về hệ điều hành, phần cứng hay API key riêng cho Ruflo. Vì vậy mình không khẳng định gì thêm. Bạn dùng Claude Code hoặc Codex thì cần tài khoản của chúng như bình thường. Nếu bạn dùng Windows, hãy xem thêm mục tài liệu trong thư mục docs/ của repo.
Các mod của Ruflo chạy với quyền của tài khoản bạn và không bị cô lập (sandbox). README dặn rõ: hãy đọc mã nguồn trước khi cài. Hãy để chế độ Claude control ở mức read + ask khi mới thử.
III.Cài đặt từng bước
README có nhiều đường cài. Mình hướng dẫn đường chính (CLI) trước, rồi nói các đường phụ.
- Mở terminal đúng thư mụcVào thư mục dự án bạn muốn dùng Ruflo
- Chạy initChạy một lệnh npx để thêm agent, hook, bộ nhớ, MCP server
- Mở 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 tác vụDán câu lệnh mẫu để Ruflo điều phối swarm
- Mở consoleGõ /ruflo trong Claude Code để xem bảng điều khiển
A.Mở terminal trong thư mục dự án
Điểm người mới hay vấp là chạy lệnh sai chỗ. init thêm file vào thư mục hiện tại, nên bạn phải mở terminal đúng thư mục dự án của mình. Nếu chưa có dự án thử, bạn có thể tạo một thư mục trống để làm quen.
cd duong-dan-toi-du-an-cua-banĐổi duong-dan-toi-du-an-cua-ban 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 trong README:
npx ruflo@latest initnpx tải và chạy bản Ruflo mới nhất mà không cần cài toàn cục. Theo README, init thêm agent, hook, bộ nhớ và MCP server vào dự án. Bảng so sánh trong README cho biết đường này tạo các thứ 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.
Muốn cấu hình tương tác từng bước, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code và giao tác vụ đầu tiên
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thứ mới ở lần khởi động kế tiếp, nên nếu nó đang mở sẵn, hãy thoát rồi mở lại. Sau đó thử 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.D.Đường phụ: 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õ 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
/rufloNếu dùng Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal thường:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloREADME nhắc: đường plugin là bản «nhẹ», chỉ có lệnh gạch chéo và vài skill. Muốn trọn vẹn (agent, hook, daemon, MCP server) thì dùng npx ruflo@latest init.
E.Đường phụ: Codex hoặc client MCP khác
Không cần thiết lập dự án. Bạn cấu hình client với command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Cách điền cụ thể tuỳ từng client, nên bạn xem tài liệu của client đó để biết điền vào đâu.
F.Đường phụ: chạy console trong terminal thường
npx ruflo tuiThêm --plain để in ra 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 để bạn biết đã ổn:
- Sau
initvà khởi động lại Claude Code, thư mục dự án có các thư mục như.claude/và.claude-flow/cùng fileCLAUDE.md. - Trong Claude Code, gõ
/ruflothì console mở ra (nếu bạn đã càiruflo-console). - Nếu cài bằng plugin, gõ
/pluginvà kiểm tra các mod xuất hiện ở dòng «active mods». - Chạy
npx ruflo tuithì giao diện console hiện trong terminal.
Tuyệt chiêu nhỏ: hãy giao một việc nhỏ, dễ kiểm chứng (ví dụ ở phần sau) thay vì việc lớn. Nếu Claude Code phản hồi và console ghi nhận hành động, bạn đã cài thành công.
V.Dùng vào việc thật
README mô tả công cụ khá rộng, nên mình chỉ chọn các tình huống bám sát những gì tư liệu nói.
A.Rà soát một dự án vừa nhận bàn giao
Bạn là lập trình viên mới nhận lại một dự án cũ, chưa biết chỗ nào dễ hỏng. Sau khi init và mở lại Claude Code, bạn dán đúng 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 Code điều phối nhóm agent để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn nên đọc kỹ phần tóm tắt và chạy lại test trước khi giữ thay đổi.
Đừng cố học hết hàng trăm công cụ, hãy cài một lệnh rồi giao cho nó một việc thật.
Ông T
B.Tạo một «mission» và giữ quyền kiểm soát
Bạn muốn thử cho Claude thao tác trên console nhưng vẫn yên tâm. README có một kịch bản năm bước. Cài console, gõ /ruflo, vào Settings → Claude control và chọn write + ask. Rồi 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ờ. Kết quả: mục Missions có mục tiêu mới và Overview ghi lại hành động. README lưu ý rõ: tạo mission không có nghĩa tính năng đã được làm xong. Muốn dừng, bấm Take back control; lệnh gọi sau đó của Claude sẽ bị từ chối cho đến khi bạn trả quyền lại.
C.Dùng Ruflo từ Codex hoặc công cụ MCP khác
Bạn đang dùng Codex hoặc một ứng dụng hỗ trợ MCP chứ không phải Claude Code. Bạn khai báo một 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 gọi được các công cụ MCP của Ruflo (README nói có 406 công cụ MCP, nhưng bạn không cần dùng hết).
D.Thêm plugin cho đúng nhu cầu
Bạn là dev làm việc nhóm và chỉ cần vài thứ. Ví dụ muốn theo dõi chi phí token thì có ruflo-cost-tracker; muốn tìm kiếm trong bộ nhớ thì có ruflo-rag-memory; muốn sinh test thì có ruflo-testgen. Cài từng cái bằng cú pháp của README:
/plugin install ruflo-cost-tracker@rufloRồi gõ /ruflo market trong console để xem Plugin Catalog, nơi có nút cài, bật, tắt, cập nhật (mỗi thao tác đều hỏi lại bạn trước).
VI.Lỗi hay gặp và cách xử lý
Chạy lệnh nhưng Claude Code không thấy gì mới. Thường do bạn chưa khởi động lại Claude Code hoặc mở nó ở thư mục khác. Hãy thoát, mở lại ngay trong thư mục đã chạy init. Với plugin, chạy /reload-plugins.
Lệnh /plugin hoặc claude plugin install báo không nhận. README yêu cầu Claude Code 2.1.287 trở lên cho đường plugin, và 2.1.292 trở lên cho lệnh cài từ terminal. Hãy cập nhật Claude Code trước.
Báo lỗi phiên bản Node. package.json yêu cầu Node 20.0.0 trở lên. Kiểm tra bằng node --version, rồi nâng cấp nếu thấp hơn.
Cài hai lần cùng một plugin từ hai marketplace. 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, nếu không mod và lệnh sẽ tải hai lần. Chọn một nguồn rồi gỡ nguồn còn lại.
Tên công cụ MCP không khớp tài liệu. README giải thích plugin ruflo-core đăng ký MCP server riêng, nên công cụ có tên dạng mcp__plugin_ruflo-core_ruflo__*, khác tên ngắn của đường CLI. Muốn đúng tên theo tài liệu CLI, hãy dùng npx ruflo@latest init.
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. Phạm vi rất rộng: agent, bộ nhớ, console, plugin, hỗ trợ cả Claude Code lẫn Codex và client MCP. Cơ chế quyền (read, write, manage, full cùng ask hoặc auto) cho bạn giữ quyền quyết định.
Giới hạn. Hệ thống lớn, nhiều khái niệm (swarm, federation, mod, plugin), người mới dễ choáng. Đường cài đầy đủ thêm nhiều file vào dự án, nên cần xem lại thay đổi. README tự nhận một số phần là «mô hình khái niệm», và các đoạn demo dùng dữ liệu mẫu, không phải bằng chứng cho việc swarm đã hoàn thành công việc thật. Bạn nên tự kiểm chứng kết quả. Các mod chạy không sandbox, nên cần đọc mã trước khi cài. README cũng không nói về chi phí gọi mô hình, nên bạn cần tự theo dõi token (có plugin cost-tracker cho việc này).
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code làm việc nhỏ lẻ, dùng Claude Code thuần là đủ và gọn hơn. Nếu bạn muốn thử nhẹ, hãy cài từng plugin qua /plugin thay vì chạy init. Còn nếu bạn muốn thử nghiệm làm việc nhiều agent, có bộ nhớ và giám sát, Ruflo là một lựa chọn đáng thử, nhất là khi bạn bắt đầu từ một dự án nhỏ.
Câu hỏi thường gặp
Ruflo có miễn phí không?
Mã nguồn Ruflo dùng giấy phép MIT và cài bằng npx. Tuy vậy Ruflo bao quanh Claude Code và Codex, nên chi phí dùng các dịch vụ đó vẫn tính theo tài khoản của bạn. Tư liệu không nêu bảng giá riêng, và có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.
Cài Ruflo có khó không?
Đường chính chỉ là một lệnh `npx ruflo@latest init` chạy trong thư mục dự án, rồi mở lại Claude Code. Bạn cần Node 20 trở lên. Bạn cũng có thể cài chỉ qua plugin bằng các lệnh `/plugin` nếu không muốn thêm file vào dự án.
Ruflo khác gì dùng Claude Code thuần?
Theo README, Ruflo là lớp bao quanh Claude Code và Codex, thêm agent chuyên biệt, hook tự định tuyến, bộ nhớ qua các phiên, console theo dõi và MCP server. Claude Code thuần không có sẵn các phần đó. Với việc nhỏ lẻ, Claude Code thuần có thể là đủ.
Ruflo có dùng được với Codex hoặc công cụ khác 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 cụ thể tuỳ từng client, tư liệu không hướng dẫn chi tiết.
Cần GPU hay cấu hình máy mạnh không?
Tư liệu mà mình có không nêu yêu cầu GPU hay cấu hình phần cứng cho đường cài chính. README chỉ nói rõ Node 20 trở lên và phiên bản Claude Code tối thiểu cho đường plugin. Một vài plugin riêng như ruflo-ruvector có nhắc tìm kiếm tăng tốc GPU, nhưng đây là tuỳ chọn.
Chạy được trên Windows không?
README phần tư liệu mình có không nói rõ về hệ điều hành. Ruflo chạy qua Node và npx, nên bạn có thể thử, nhưng chưa có thông tin xác nhận cụ thể. Bạn nên xem thư mục docs trong repo hoặc phần Issues nếu gặp vấn đề.
Ruflo có an toàn khi cho Claude điều khiển không?
README cho biết mặc định là read + ask, và các hành động vượt quyền sẽ bị từ chối. Hành động liên quan mạng, chi tiêu, phá hủy vẫn cần xác nhận kể cả ở chế độ auto, và bạn có nút Take back control. Tuy nhiên các mod chạy với quyền tài khoản của bạn và không sandbox, nên cần đọc mã trước khi cài.


