Ruflo: điều phối nhiều 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 là một agent harness (lớp điều phối) bao quanh Claude Code và Codex, thêm agent, bầy agent (swarm), bộ nhớ dài hạn, hook và MCP server vào dự án của bạn. Bạn dùng nó để giao việc lớn cho nhiều agent phối hợp thay vì một agent đơn lẻ. Cài khá dễ: chỉ cần Node 20 trở lên và chạy một lệnh npx trong thư mục dự án.
Ruflo là một «agent harness»: lớp công cụ bao quanh Claude Code và Codex, giúp mô hình AI không chỉ trả lời mà còn làm việc có tổ chức. Nó bổ sung agent chuyên biệt, bầy agent phối hợp (swarm), bộ nhớ qua nhiều phiên, hook tự động 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.
Tác giả diễn đạt ý tưởng đơn giản thế này: Agent = Model + Harness. Mô hình 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 kiểm soát để agent làm việc được thật. Ruflo chính là phần harness đó.
Bạn nên xem Ruflo nếu đang dùng Claude Code hoặc Codex và muốn giao những việc dài hơi: rà soát cả repo, viết test, theo dõi tiến độ nhiều bước. Điểm đáng giá nhất là bạn không phải học hết công cụ. README nói rõ: sau khi init, cứ dùng Claude Code như bình thường, hệ thống hook sẽ tự định tuyến việc, học từ các lần thành công và điều phối agent ở nền.
ruvnet/ruflo
Ruflo là lớp điều phối bao quanh Claude Code và Codex: thêm agent chuyên biệt, bộ nhớ, hook và MCP server vào dự án chỉ bằng một lệnh npx.
I.Ruflo làm được gì
Tài liệu của repo khá rộng. Dưới đây là những phần dễ thấy lợi ích nhất với người mới.
A.Agent và swarm
Sau khi cài theo cách đầy đủ, dự án của bạn có sẵn khoảng 98 agent, hơn 60 lệnh và 30 skill (theo bảng so sánh trong README). Các agent có thể tự tổ chức thành swarm, tức một nhóm chia việc cho nhau. Lợi ích thực tế: bạn mô tả một mục tiêu lớn, Claude Code có thể chia nhỏ rồi giao cho nhiều agent thay vì tự làm tuần tự.
B.Bộ nhớ qua nhiều phiên
Ruflo có bộ nhớ vector để agent nhớ lại thứ đã làm ở các phiên trước. Các plugin như ruflo-agentdb, ruflo-rag-memory và ruflo-rvf phụ trách việc lưu, tìm kiếm và khôi phục bộ nhớ. Với người dùng, điều này nghĩa là đỡ phải giải thích lại bối cảnh dự án mỗi lần mở máy.
C.Học từ kinh nghiệm
README mô tả một vòng học: kinh nghiệm từ các tác vụ thành công được đưa ngược lại vào việc định tuyến. README cũng ghi thận trọng rằng đây là sơ đồ khái niệm, và phần học cục bộ vẫn cần embedding cùng các module học được cấu hình. Bạn đừng kỳ vọng nó tự thông minh lên ngay.
D.Bảng điều khiển (console) trong Claude Code
Plugin ruflo-console cho bạn một «buồng lái» cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí. Bạn mở bằng lệnh /ruflo. Có thể xem log từng agent, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy.
E.Cho Claude điều khiển, nhưng bạn đặt giới hạn
Trong Settings → Claude control, bạn chọn mức quyền read, write, manage hoặc full, và chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask. 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 hoặc phá hủy vẫn phải xác nhận kể cả khi để auto. Có nút «Take back control» để thu quyền lại.
F.Hệ sinh thái 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, kiểm thử, bảo mật, DevOps... Ví dụ ruflo-testgen tìm test còn thiếu và sinh test, ruflo-security-audit quét lỗ hổng, ruflo-cost-tracker theo dõi token và đặt ngân sách. Bạn chỉ cần cài cái mình cần.
G.Liên kết nhiều máy và nhiều công cụ
Ruflo hỗ trợ federation (agent ở các máy khác nhau phối hợp) và có thể dùng với Codex hoặc client MCP khác. README cũng có lệnh npx ruflo init --grok cho Grok Build. 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.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js phiên bản 20.0.0 trở lên (package.json yêu cầu
>=20.0.0). - Claude Code (hoặc Codex, hoặc một client MCP khác) để dùng cùng.
- Nếu chọn cách cài bằng plugin: Claude Code phiên bản 2.1.287 trở lên. Lệnh cài từ terminal thì cần 2.1.292 trở lên.
- 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 hay GPU, và README phần đầu không nói rõ cần API key nào. Ruflo chạy bên cạnh Claude Code hoặc Codex nên bạn vẫn cần tài khoản hợp lệ của công cụ đó. Plugin ruflo-ruvector có nhắc tìm kiếm tăng tốc GPU, nhưng đó là tùy chọn riêng của plugin, không phải điều kiện để dùng Ruflo.
Các mod của Ruflo chạy với quyền tài khoản của bạn và không bị đặt trong sandbox. README khuyên đọc mã nguồn trước khi cài. Hãy để chế độ Claude control ở mức read + ask khi mới làm quen.
III.Cài đặt từng bước
README có nhiều đường cài. Cách đơn giản và đầy đủ nhất là npx ruflo@latest init. Hai cách còn lại (plugin và MCP) mình trình bày sau để bạn chọn.
- Kiểm tra NodeChắc chắn máy có Node 20 trở lên
- 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ở Claude Code trong cùng thư mục để nó nhận cấu hình
- Giao việc thửDán một câu lệnh mẫu để xem swarm làm việc
A.Kiểm tra Node
Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và xem phiên bản Node. Lệnh node --version là lệnh phổ thông. Kết quả phải từ v20 trở lên.
node --versionNếu thấp hơn 20, bạn cần nâng cấp Node trước. README không hướng dẫn việc này, hãy xem trang chính thức của Node.js.
B.Mở terminal đúng thư mục
Đây là chỗ người mới hay vấp nhất. Lệnh init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong thư mục dự án. Nếu bạn chưa có thư mục nào, tạo một thư mục thử rồi cd vào đó.
cd đường-dẫn-tới-dự-án-của-bạnThay phần sau cd bằng đường dẫn thật trên máy bạn.
C.Chạy init
Đây là lệnh chính theo README:
npx ruflo@latest initnpx tải và chạy gói tạm thời, không cần cài toàn cục. Lệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh trong README, cách này tạo các mục như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings trong workspace. Vì vậy hãy chạy trong dự án có dùng git để dễ xem những gì đã thay đổi.
Nếu muốn thiết lập theo kiểu hỏi đáp, README ghi có lệnh:
npx ruflo@latest init wizardD.Mở lại Claude Code và giao việc thử
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thành phần ở lần khởi động kế tiếp. Nếu Claude Code đang mở sẵn, hãy thoát ra và mở lại. Sau đó thử một việc thật, 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.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 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
/rufloTừ terminal, trên Claude Code 2.1.292 trở lên, README ghi lệnh:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý README nói rõ cách plugin là bản «nhẹ»: chỉ có lệnh slash, vài skill và định nghĩa agent. Không có hook, và MCP server chỉ được đăng ký khi bạn cài ruflo-core. Muốn dùng đủ vòng lặp của Ruflo thì chọn npx ruflo@latest init.
F.Cách khác: Codex hoặc client MCP khác
Với Codex hay client MCP, bạn cấu hình lệnh (command) là npx và đối số (arguments) như sau:
["-y", "ruflo@latest", "mcp", "start"]Tương đương dòng lệnh npx -y ruflo@latest mcp start. Cách này không cần thiết lập dự án.
G.Cách khác: giao diện terminal
Bảng điều khiển còn chạy độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain nếu muốn in ra một khung hình dùng cho script.
IV.Kiểm tra đã chạy được chưa
Sau npx ruflo@latest init, hãy kiểm tra theo thứ tự này:
- Trong thư mục dự án có xuất hiện các mục như
.claude/,.claude-flow/vàCLAUDE.md(theo README cho cách cài CLI). - Mở lại Claude Code trong thư mục đó, rồi gõ
/ruflo. Nếu bảng điều khiển hiện ra, phần console đã hoạt động. - Nếu cài bằng plugin, gõ
/pluginđể xem các mod có nằm trong dòng «active mods» không. - Giao thử câu lệnh swarm mẫu ở trên và xem Claude Code có phản hồi bằng cách dùng agent của Ruflo hay không.
README không đưa ra một dòng kết quả cố định kiểu «cài thành công». Vì vậy cách kiểm tra đáng tin nhất là thấy file mới xuất hiện và /ruflo mở được.
V.Dùng vào việc thật
A.Lập trình viên rà soát một repo lạ
Bối cảnh: bạn vừa nhận một dự án cũ, chưa ai viết test. Chạy npx ruflo@latest init trong thư mục dự án, mở lại Claude Code rồi 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: agent chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Hãy đọc kỹ phần test được sinh ra trước khi gộp vào nhánh chính. Vì có hạ tầng nhiều agent, bạn nên xem lại chứ không nên tin ngay.
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 mới theo dõi agent bằng bảng điều khiển
Bối cảnh: bạn muốn biết agent đang làm gì và tốn bao nhiêu token. Cài plugin ruflo-console theo cách plugin ở trên, rồi gõ /ruflo. Bạn xem được workflow, agent, model, token và chi phí; mở log từng agent để biết nó đã làm gì khi có lỗi. Kết quả: bạn nhìn thấy quá trình thay vì chờ một kết quả cuối không rõ nguồn gốc.
C.Giao Claude tạo «mission» có kiểm soát
Bối cảnh: bạn muốn thử cho Claude điều khiển bảng điều khiển nhưng sợ nó làm quá tay. README có một ví dụ từng bước:
- Mở
/ruflo, vào Settings → Claude control, chọn write + ask. - Đưa yêu cầu cụ thể:
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 có ghi lại hành động.
- Bấm «Take back control» khi muốn dừng quyền của Claude.
README nhắc rõ: tạo mission không có nghĩa là tính năng đã được làm xong.
D.Nhóm nhỏ kiểm soát chi phí và chất lượng bằng plugin
Bối cảnh: một nhóm nhỏ dùng Claude Code hằng ngày và lo chi phí token. Họ cài thêm plugin theo cú pháp /plugin install <tên>@ruflo, ví dụ ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí) và ruflo-testgen (tìm test thiếu và sinh test). README chỉ mô tả ngắn gọn chức năng, nên hãy thử trên một dự án nhỏ trước khi đưa vào quy trình chính.
VI.Lỗi hay gặp và cách xử lý
A.Chạy lệnh nhưng Claude Code không thấy gì mới
Nguyên nhân hay gặp: Claude Code đang mở từ trước hoặc mở sai thư mục. README nói các thành phần được nhận ở lần khởi động kế tiếp. Hãy thoát Claude Code, mở lại đúng thư mục đã chạy init. Với plugin, thử /reload-plugins.
B.Báo lỗi phiên bản Node
Nếu npx báo lỗi lạ, hãy chạy node --version. Tư liệu yêu cầu Node 20 trở lên. Nâng Node lên rồi chạy lại.
C.Lệnh /plugin install không chạy hoặc không có
Cách plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 trở lên cho lệnh claude plugin install ở terminal). Cập nhật Claude Code trước. Nhớ gõ các lệnh /plugin ... bên trong Claude Code, không gõ vào terminal thường.
D.Tên công cụ MCP không khớp khi dùng cách plugin
README giải thích: với plugin ruflo-core, công cụ có tên dạng mcp__plugin_ruflo-core_ruflo__memory_store, khác tên ngắn như memory_store của cách cài CLI. Nếu bạn làm theo tài liệu viết cho cách CLI mà dùng cách plugin, tên sẽ lệch. Hãy chọn một cách cho nhất quán, hoặc dùng cách CLI nếu muốn đúng như tài liệu.
E.Cài trùng plugin từ hai nguồn
Với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow, README dặn chỉ cài từ một marketplace. Nếu bật từ cả hai, mod và lệnh có thể tải hai lần. Hãy gỡ một bên.
VII.Có nên dùng không
Điểm mạnh: cài nhanh bằng một lệnh, giấy phép MIT, cộng đồng lớn, repo vẫn được cập nhật trong vài tháng gần đây. Nó cho bạn phần điều phối, bộ nhớ và bảng theo dõi mà Claude Code mặc định không có. Cơ chế phân quyền (read/write/manage/full, ask/auto) cũng cho bạn quyền kiểm soát rõ ràng.
Giới hạn: dự án rất lớn (README nhắc tới 406 công cụ MCP và 61 lệnh CLI), nên người mới dễ bị ngợp. Cách cài đầy đủ ghi khá nhiều file vào dự án. Phần tự học được README mô tả là «khái niệm», chưa phải thứ bạn nên mặc định tin. Các mod không bị sandbox, nên cần đọc mã trước khi cài.
Nên chọn cách khác khi: bạn chỉ cần Claude Code cho việc nhỏ lẻ, một agent là đủ; hoặc bạn không muốn thêm file cấu hình vào dự án (khi đó thử cách plugin, hoặc không dùng). Nếu bạn là người mới, hãy bắt đầu với npx ruflo@latest init trong một dự án thử, giao một việc nhỏ, rồi mở /ruflo để xem nó làm gì trước khi dùng cho công việc thật.
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 và sửa tự do. Tư liệu không nói gì về chi phí của Claude Code, Codex hay các nhà cung cấp mô hình mà bạn dùng cùng Ruflo. Plugin ruflo-cost-tracker có thể giúp theo dõi token và đặt ngân sách.
Cài Ruflo bằng lệnh nào?
Trong thư mục dự án, chạy `npx ruflo@latest init`, rồi mở lại Claude Code ở cùng thư mục. Nếu muốn thiết lập theo kiểu hỏi đáp, README ghi có `npx ruflo@latest init wizard`. Cần Node 20 trở lên.
Ruflo có cần GPU không?
Tư liệu không nêu yêu cầu GPU cho Ruflo. Chỉ có plugin ruflo-ruvector được mô tả là tìm kiếm tăng tốc GPU, và đó là tùy chọn riêng. Với yêu cầu phần cứng cụ thể, bạn nên xem thêm trong tài liệu của repo.
Dùng được với Codex hay chỉ Claude Code?
Dùng được cả hai. README ghi Codex và các client MCP khác trỏ tới lệnh `npx -y ruflo@latest mcp start`. Ngoài ra có tùy chọn `npx ruflo init --grok` cho Grok Build.
Cách cài bằng plugin khác gì cách `npx ruflo init`?
Cách plugin không thêm file nào vào workspace, chỉ cho lệnh slash, vài skill và định nghĩa agent; MCP server chỉ có khi cài ruflo-core, và không có hook. Cách `npx ruflo init` cho đủ vòng lặp: 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon, đổi lại ghi thêm file vào dự án.
Claude có thể tự làm bậy trên bảng điều khiển không?
README nói bạn đặt giới hạn bằng mức quyền read, write, manage hoặc full, cùng chế độ ask hoặc auto. Mặc định hiện là read + ask. Hành động mạng, chi tiêu và phá hủy vẫn cần xác nhận kể cả khi để auto, và có nút Take back control để thu quyền.
Chạy được trên Windows không?
Tư liệu không nêu rõ hệ điều hành được hỗ trợ. Điều kiện duy nhất được ghi là Node 20 trở lên, và các lệnh đều dựa trên npx. Bạn nên thử trên một dự án nhỏ trước, hoặc xem thêm tài liệu trong repo.


