ruflo: điều phối đội agent và bộ nhớ cho Claude Code, 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 điều phối bao quanh Claude Code và Codex để bổ sung đội agent, bộ nhớ qua các phiên, hook và MCP server. Bạn cài bằng một lệnh npx trong thư mục dự án, cần Node từ 20 trở lên. Với người đã quen dùng Claude Code, việc cài khá đơn giản.
Ruflo là một "bộ khung điều phối" (agent harness) bọc quanh Claude Code và Codex. Nó thêm vào dự án của bạn các agent chuyên biệt, bộ nhớ giữ qua nhiều phiên làm việc, 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.
Nói đơn giản: mô hình AI là người viết, còn harness là cái bàn làm việc xung quanh nó, gồm công cụ, trí nhớ, vòng lặp và các giới hạn an toàn. Ruflo là cái bàn làm việc đó. Bạn vẫn dùng Claude Code như thường, nhưng phía sau có thêm một lớp giúp chia việc cho nhiều agent, nhớ lại kinh nghiệm cũ và theo dõi tiến độ.
Repo hợp với lập trình viên đã dùng Claude Code hoặc Codex và muốn giao những việc lớn hơn, như review cả repo, viết test, theo dõi chi phí. Người mới cũng thử được: README nói bạn không cần học hết hàng trăm công cụ, chỉ cần chạy lệnh khởi tạo rồi dùng Claude Code bình thường. Điểm đáng giá nhất là cài một lệnh, có luôn một "buồng lái" (console) để xem agent đang làm gì.
ruvnet/ruflo
Ruflo là bộ khung điều phối bọc quanh Claude Code và Codex, thêm đội agent, bộ nhớ, hook và MCP server vào dự án chỉ với một lệnh npx.
I.Ruflo làm được gì
Dưới đây là các nhóm tính năng chính, mô tả theo lợi ích thực tế.
- Đội agent chuyên biệt và swarm. README nói có hơn 100 agent chuyên biệt, và khi cài bằng
npx ruflo initbạn nhận 98 agent. Chúng có thể tự tổ chức thành "swarm" (đàn) để chia nhau một việc lớn. Bạn chỉ cần nói "dùng swarm của ruflo để làm việc này" thay vì tự điều phối từng agent. - Bộ nhớ qua nhiều phiên. Agent nhớ lại những gì đã làm ở phiên trước và học từ các việc đã thành công. README lưu ý đây là mô hình khái niệm: phần truy xuất vector cục bộ có thể chạy không cần LLM, nhưng vẫn cần embedding và các module học được cấu hình.
- Hook tự động. Sau khi khởi tạo, hook sẽ tự định tuyến việc, học từ mẫu thành công và phối hợp agent ngầm. Bạn không phải gọi từng công cụ.
- Console
/ruflongay cạnh Claude Code. Bạn xem được workflow, agent, model, token và chi phí. Bạn cũng mở được log và kết quả từng lần chạy, tìm kiếm, tìm lỗi, phát lại và so sánh. - Cho Claude lái console, bạn đặt giới hạn. Trong Settings, mục Claude control có bốn mức:
read,write,manage,full, kèm chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các thao tác ngoài mạng, tốn tiền hoặc phá hủy vẫn phải xác nhận kể cả khi đểauto. - Kho plugin. Có 48 plugin (cộng thêm 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, vận hành, theo dõi chi phí và mở rộng. Ví dụ
ruflo-testgentìm test còn thiếu và tạo test,ruflo-cost-trackertheo dõi token và đặt ngân sách,ruflo-aidefencechặn prompt injection. - Federation. Agent trên các máy khác nhau có thể liên lạc an toàn với nhau mà không làm lộ dữ liệu, theo mô tả của README.
- Chạy nhiều nơi. Ngoài Claude Code, Codex và các client MCP khác dùng được. README còn có lệnh
npx ruflo init --grokcho Grok Build.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu một số yêu cầu rõ ràng:
- Node.js từ 20.0.0 trở lên. Đây là yêu cầu trong
package.json. - Claude Code nếu bạn đi theo đường chính. Nếu dùng đường plugin thì cần Claude Code 2.1.287 trở lên. Lệnh cài plugin từ terminal (
claude plugin install ...) cần Claude Code 2.1.292 trở lên. - Codex hoặc một MCP client khác nếu bạn không dùng Claude Code. Client chỉ cần cấu hình được một lệnh MCP.
- Một thư mục dự án để chạy lệnh khởi tạo. Lệnh sẽ thêm file vào thư mục này.
Còn các điều sau thì README (phần mình có) chưa nói rõ: hệ điều hành nào được hỗ trợ chính thức, có cần API key riêng hay không, và có cần GPU hay không. Bạn nên xem thêm trong repo (README đầy đủ và thư mục docs) trước khi dùng cho việc quan trọng.
Ruflo thêm file vào dự án (như .claude/, .claude-flow/, CLAUDE.md, cấu hình hook). Hãy thử trên một dự án nhỏ hoặc đã commit sạch trước, để dễ so sánh và hoàn tác nếu cần.
III.Cài đặt từng bước
Có ba đường cài. Mình xếp đường đơn giản nhất lên đầu. Tóm tắt đường chính:
- Mở terminal đúng chỗVào thư mục dự án bạn muốn dùng
- Chạy lệnh initCài agent, hook, bộ nhớ và MCP server vào dự án
- Mở lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thậtGõ yêu cầu dùng swarm của ruflo
A.Mở terminal trong thư mục dự án
Lệnh khởi tạo ghi file vào thư mục hiện tại, nên bạn phải đứng đúng chỗ. Chỗ người mới hay vấp là chạy lệnh ở thư mục sai (ví dụ thư mục Downloads), khiến file bị ghi nhầm nơi. Trên Windows, bạn có thể mở thư mục dự án rồi mở PowerShell từ đó.
cd duong-dan-toi-du-an-cua-banThay duong-dan-toi-du-an-cua-ban bằng đường dẫn thật tới dự án của bạn. Kiểm tra Node bằng node --version và chắc chắn số phiên bản từ 20 trở lê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 mà không cần cài toàn cục. README nói init thêm agent, hook, bộ nhớ và MCP server của ruflo vào dự án. Bảng so sánh trong README cho biết đường này tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md cùng một số file hỗ trợ và settings.
Nếu muốn thiết lập theo kiểu hỏi đáp, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code và giao việc đầu tiên
Claude Code đọc cấu hình mới khi khởi động lại, nên hãy mở (hoặc mở lại) Claude Code trong đúng thư mục vừa chạy init. Sau đó giao một việc thật, ví dụ 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.Bạn có thể viết bằng tiếng Việt, nhưng câu mẫu bằng tiếng Anh ở trên là câu README đã thử. Ý nghĩa: dùng swarm của ruflo để review repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã 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. README cho biết nó cài công cụ lõi, console trực quan và các mod chạy trong Claude Code. Chạy 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
/rufloCác dòng này gõ vào khung chat của Claude Code, không phải vào PowerShell. Dòng đầu thêm kho plugin của ruflo, ba dòng install cài từng plugin, /reload-plugins nạp lại, còn /ruflo mở console. Nếu dùng Claude Code 2.1.292 trở lên, bạn cũng cài được từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý trong README: mod chạy với quyền tài khoản của bạn và không bị cô lập, nên hãy đọc mã trước khi cài.
E.Cách khác: Codex hoặc client MCP khác
Nếu không dùng Claude Code, hãy cấu hình client với command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]README cũng nêu cách viết gộp trên một dòng: npx -y ruflo@latest mcp start. Cách nhập cụ thể phụ thuộc client của bạn, nên hãy xem tài liệu của client đó để biết điền command và arguments vào đâu.
F.Cách khác: chạy console trên terminal
Console chạy được riêng, không cần Claude Code:
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
Tư liệu không mô tả một dòng kết quả cố định để so khớp, nên mình gợi ý các dấu hiệu theo đúng những gì README nói:
- Sau
init: trong thư mục dự án xuất hiện.claude/,.claude-flow/vàCLAUDE.md. Mở lại Claude Code rồi gõ/ruflođể mở console. - Sau khi cài plugin: mở
/pluginđể xem plugin có nằm trong dòng "active mods" không. README hướng dẫn kiểm tra theo cách này. - Với console: thử bài mẫu của README. Vào Settings, chọn Claude control, đặt write + ask. Sau đó nhờ Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status." Bạn xác nhận thao tác tạo, rồi kiểm tra mục Missions có mục tiêu đó và Overview có ghi lại hành động.
- Với terminal UI:
npx ruflo tuimở được màn hình console là đạt.
Một điểm README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Đó chỉ là bản ghi mục tiêu.
V.Dùng vào việc thật
A.Dev review nhanh một repo cũ
Bạn vừa nhận một repo cũ, chưa biết bắt đầu từ đâu. Trong thư mục đó, chạy npx ruflo@latest init, mở Claude Code rồi giao 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.Bạn nhận lại ba thứ: module bị đánh giá rủi ro nhất, các test mới cho module đó, và bản tóm tắt thay đổi. Hãy đọc kỹ bản tóm tắt và chạy test trước khi tin kết quả.
Agent = Model + Harness: mô hình viết, còn harness cho nó công cụ, trí nhớ và giới hạn để làm việc thật.
Ông T
B.Người mới theo dõi agent qua console
Bạn là lập trình viên mới, muốn nhìn thấy agent làm gì thay vì chỉ đọc chữ chạy trong terminal. Cài bằng đường plugin (ruflo-core, ruflo-console, ruflo-mods), gõ /ruflo, rồi vào Settings → Claude control và chọn write + ask. Nhờ Claude tạo một mission, ví dụ thêm nút bật tắt chế độ tối. Bạn tự xác nhận từng thao tác. Kết quả là bạn thấy mission trong Missions và nhật ký hành động trong Overview. Nếu cần dừng, bấm Take back control để Claude ngừng điều khiển console.
C.Dùng Codex hoặc công cụ khác qua MCP
Bạn dùng Codex (hoặc client MCP khác) và không muốn đổi công cụ. Cấu hình client với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Client sẽ gọi được bộ công cụ của ruflo mà không cần thiết lập dự án. Nếu muốn thiết lập có hướng dẫn cho từng dự án, chạy npx ruflo@latest init wizard.
D.Theo dõi chi phí và chất lượng bằng plugin
Nếu bạn đang dùng agent chạy nhiều lần và lo hóa đơn token, README liệt kê plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí) và ruflo-testgen (tìm test còn thiếu rồi tạo test). Cài bằng cú pháp /plugin install <tên>@ruflo, giống các plugin ở trên. Cách cấu hình chi tiết từng plugin mình chưa có trong tư liệu, nên bạn xem trong thư mục plugins của repo.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx báo lỗi hoặc không chạy. Kiểm tra node --version. package.json yêu cầu Node từ 20.0.0 trở lên. Nếu máy bạn dùng bản cũ hơn, hãy cập nhật Node rồi chạy lại.
Lệnh /plugin không nhận hoặc không cài được plugin. Đườ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). Hãy cập nhật Claude Code, rồi chạy lại /plugin marketplace add ruvnet/ruflo.
Cài xong nhưng không thấy gì mới. Với init, hãy mở lại Claude Code trong đúng thư mục đã chạy lệnh, vì cấu hình chỉ được nạp lúc khởi động. Với plugin, chạy /reload-plugins, rồi mở /plugin để xem plugin có trong danh sách đang chạy không.
Claude từ chối thao tác trong console. Đây là thiết kế an toàn: thao tác vượt quá mức quyền bạn đặt sẽ bị từ chối. Mặc định là read + ask. Nếu cần ghi hoặc tạo, nâng lên write trong Settings → Claude control và nhớ vẫn để chế độ ask để tự duyệt. Muốn dừng ngay, bấm Take back control.
Plugin bên ngoài bị tải hai lần. README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb và agentic-flow: chỉ cài từ một marketplace duy nhất, vì bật từ cả hai nơi thì mod và lệnh sẽ nạp đôi. Nếu thấy lệnh bị trùng, gỡ bản ở một nơi.
VII.Có nên dùng không
Điểm mạnh. Cài đặt chỉ một lệnh cho đường chính. Giấy phép MIT. Repo vẫn được cập nhật trong 3 tháng gần đây. Có nhiều đường vào (init, plugin, MCP, terminal UI) cho nhiều kiểu người dùng. Phần giới hạn quyền của console (read, write, manage, full, kèm ask hoặc auto) cho bạn quyền kiểm soát rõ ràng.
Giới hạn. Hệ sinh thái rất lớn: README nói 406 công cụ MCP, 61 lệnh CLI và 48 plugin, nên người mới dễ choáng. Cứ bắt đầu bằng init rồi dùng Claude Code như bình thường. Đường init ghi khá nhiều file vào dự án. Mod chạy với quyền tài khoản của bạn và không bị cô lập. README cũng nói rõ các bản demo dùng dữ liệu mẫu hoặc replay khung hình, không phải bằng chứng cho việc swarm hay bộ nhớ đã hoàn thành công việc. Còn chi phí API, hệ điều hành hỗ trợ và yêu cầu phần cứng thì tư liệu mình có chưa nói.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code làm các việc nhỏ, đơn lẻ, thì chưa cần thêm một lớp điều phối. Nếu chỉ muốn thử một vài lệnh, hãy cài từng plugin lẻ thay vì cả bộ. Còn nếu cần dùng cho sản phẩm thật, hãy thử trên dự án nhỏ trước, đọc SECURITY.md trong repo và kiểm tra kết quả bằng test của bạn.
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 mã nguồn dùng được tự do. Tư liệu mình có chưa nói về chi phí gọi mô hình AI phía sau, nên bạn cần xem gói Claude Code, Codex hoặc nhà cung cấp mà bạn đang dùng. Ruflo có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.
Cài ruflo cần những gì?
Cần Node.js từ 20.0.0 trở lên. Nếu đi đường plugin thì cần Claude Code 2.1.287 trở lên, còn lệnh cài từ terminal cần 2.1.292 trở lên. Lệnh chính là npx ruflo@latest init chạy trong thư mục dự án.
Ruflo có cần GPU không?
Tư liệu mình có chưa nêu yêu cầu GPU cho đường cài chính. README có nhắc plugin ruflo-ruvector dùng tìm kiếm tăng tốc GPU, nhưng đó là một plugin riêng. Bạn nên xem tài liệu của plugin đó nếu cần.
Ruflo có chạy trên Windows được không?
README phần mình có không nêu rõ danh sách hệ điều hành hỗ trợ. Các lệnh cài đều là npx và lệnh trong Claude Code, nên điều kiện quan trọng là có Node 20 trở lên. Bạn nên kiểm tra thêm trong repo hoặc thử trên dự án nhỏ trước.
Dùng ruflo thì có phải dùng Claude Code không?
Không bắt buộc. Ruflo hỗ trợ Claude Code và Codex, và bất kỳ client MCP nào cũng có thể trỏ tới lệnh npx -y ruflo@latest mcp start. Bạn cũng có thể chạy console độc lập bằng npx ruflo tui.
Claude có tự làm những việc nguy hiểm trong console không?
Theo README, mặc định là read + ask. Thao tác vượt mức quyền bạn chọn sẽ bị từ chối. Các thao tác liên quan mạng, chi tiền hoặc phá hủy luôn cần bạn xác nhận, kể cả khi để auto. Bạn có thể bấm Take back control để dừng.
Plugin của ruflo có an toàn không?
README cảnh báo rõ: mod chạy với quyền của tài khoản bạn và không bị cô lập (sandbox), nên bạn nên đọc mã trước khi cài. Tư liệu mình có chưa có đánh giá bảo mật độc lập nào. Repo có file SECURITY.md để bạn tham khảo.


