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 (tiền thân là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex để nhiều agent phối hợp, có bộ nhớ và có hooks. Bạn chỉ cần chạy một lệnh npx trong thư mục dự án rồi mở lại Claude Code. Cài đặt không khó, nhưng repo rất lớn nên nên bắt đầu từ các bước đơn giản.
ruflo là một «agent harness» (bộ khung điều phối) bao quanh Claude Code và Codex. Hiểu đơn giản: mô hình AI là người viết, còn ruflo là bàn làm việc đầy đủ đồ nghề quanh người đó: công cụ, bộ nhớ, vòng lặp kiểm tra và các lớp kiểm soát. Nhờ vậy nhiều agent có thể cùng làm một việc thay vì mỗi con chạy một mình.
Repo này dành cho ai đã dùng Claude Code hoặc Codex và muốn đi xa hơn một cuộc trò chuyện đơn lẻ: giao một việc lớn cho cả «đội» agent, để chúng nhớ lại kinh nghiệm giữa các phiên. Người làm kinh doanh hay văn phòng cũng dùng được nếu có Claude Code, nhưng bạn nên quen việc mở terminal trước.
Điểm đáng giá nhất là độ dễ vào cửa: một lệnh npx ruflo@latest init là xong phần cài. README nói rõ bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Sau init, bạn cứ dùng Claude Code như bình thường, hệ thống hooks sẽ tự định tuyến việc và phối hợp agent ở phía sau. Hiện repo có khoảng 81.600 sao và khoảng 9.600 fork, giấy phép MIT.
ruvnet/ruflo
ruflo là bộ khung điều phối bao quanh Claude Code và Codex: thêm agent, bộ nhớ, hooks và máy chủ MCP vào dự án chỉ với một lệnh npx.
I.ruflo làm được gì
Dưới đây là những điều chính, theo cách README mô tả.
- Đội agent làm việc theo nhóm (swarm). Repo nói có hơn 100 agent chuyên biệt, tự tổ chức thành swarm. Bạn giao một việc lớn, các agent chia nhau làm thay vì một agent ôm hết.
- Bộ nhớ qua nhiều phiên. Agent nhớ được thứ đã làm ở lần trước và học từ các việc thành công. README lưu ý đây là vòng học mang tính khái niệm: truy xuất vector cục bộ chạy được mà không cần LLM, nhưng vẫn cần embedding và các module học đã cấu hình.
- Hooks tự động. Sau
init, hooks tự định tuyến tác vụ và phối hợp agent ngầm, bạn không phải gọi từng công cụ. - Máy chủ MCP. Claude Code, Codex hay client MCP khác đều nối vào được. Cách nối: lệnh
npx -y ruflo@latest mcp start. - Bảng điều khiển (console) ngay cạnh Claude Code. Theo dõi workflow, agent, mô hình, token và chi phí. Bạn xem được log, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy.
- Cho Claude lái, bạn đặt giới hạn. Mục Settings → Claude control cho Claude điều khiển console theo mức
read,write,managehoặcfull, với chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các hành động vượt quyền bị từ chối; hành động liên quan mạng, chi tiền hay phá huỷ vẫn phải xác nhận ngay cả khi ởauto. - Kho plugin. README liệt kê 48 plugin (kèm 3 plugin bên ngoài): swarm, bộ nhớ RAG, tạo test, quét bảo mật, theo dõi chi phí, tài liệu tự động và nhiều nhóm khác. Bạn cài lẻ từng cái nếu chỉ cần một vài thứ.
- Liên kết nhiều máy (federation). Agent trên các máy khác nhau trao đổi với nhau, README nói là không làm lộ dữ liệ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 (hoặc Codex / một client MCP khác). Nếu đi đường plugin của Claude Code thì cần phiên bản 2.1.287 trở lên. Lệnh cài plugin ngay từ terminal cần 2.1.292 trở lên.
- Một thư mục dự án để chạy lệnh trong đó.
Tư liệu chưa nói rõ về yêu cầu hệ điều hành, phần cứng hay API key cụ thể cho từng bước. Vì vậy mình không đoán: nếu cần, bạn xem thêm trong tài liệu docs/ của repo.
Các mod của ruflo chạy với quyền tài khoản của bạn và không bị đưa vào sandbox. README khuyên đọc mã của chúng trước khi cài. Hãy làm đúng như vậy, nhất là trên máy có dữ liệu công việc thật.
III.Cài đặt từng bước
README có hai đường chính. Đường thứ nhất (CLI) cho đầy đủ nhất, mình khuyên bạn chọn đường này.
- Mở terminalVào đúng thư mục dự án của bạn
- Chạy initLệnh npx ruflo@latest init thêm agent, hooks, bộ nhớ, MCP vào dự án
- Mở lại Claude CodeMở trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thậtDán một câu lệnh mẫu nhờ dùng swarm
- Tuỳ chọn: cài consoleDùng plugin để có bảng điều khiển /ruflo
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 ghi file vào thư mục hiện tại, nên bạn phải đứng trong dự án của mình. Ví dụ trên Windows PowerShell hoặc macOS/Linux terminal:
cd ten-thu-muc-du-an-cua-banHãy thay ten-thu-muc-du-an-cua-ban bằng đường dẫn thư mục của bạn.
B.Chạy lệnh init
Đây là lệnh chính của README:
npx ruflo@latest initnpx tải ruflo bản mới nhất rồi chạy. init thêm agent, hooks, bộ nhớ và máy chủ MCP vào dự án. README cho biết thư mục dự án sẽ có thêm .claude/, .claude-flow/, CLAUDE.md cùng các file hỗ trợ và settings. Vì vậy nếu dự án của bạn đang dùng git, bạn nên commit trước để dễ xem ruflo đã thêm gì.
Nếu muốn cài theo kiểu hỏi đáp từng bước, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code
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ếu bạn đang mở sẵn Claude Code từ trước thì hãy thoát ra và mở lại.
D.Giao một việc thật
Sau khi mở lại, thử với 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.Câu này nhờ Claude dùng swarm để rà soát dự án, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi.
E.Đường khác: chỉ cài plugin cho Claude Code
Nếu không muốn thêm file vào dự án, README có đường «plugin only». Đường này không thêm file nào vào dự án, nhưng ít tính năng hơn bản CLI (ví dụ không cài hooks). Bạ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
/rufloLần lượt: thêm kho plugin của ruflo, cài lõi, cài bảng điều khiển, cài mod, nạp lại plugin, rồi mở console bằng /ruflo. Nếu dùng Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloF.Đường khác: Codex hoặc client MCP khác
README hướng dẫn cấu hình client với command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Chỗ điền cấu hình này phụ thuộc vào client bạn dùng. Tư liệu không nêu cụ thể cho từng client, nên bạn xem mục cấu hình MCP của chính client đó.
G.Chạy console ngoài Claude Code
Bảng điều khiển còn chạy độc lập trong terminal thường:
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
Tuỳ đường cài, bạn có các dấu hiệu sau:
- Đường CLI: sau
init, trong thư mục dự án phải có.claude/,.claude-flow/vàCLAUDE.md. Mở lại Claude Code rồi gõ/ruflođể mở console. - Đường plugin: gõ
/plugintrong Claude Code và xem các mod đã cài có xuất hiện ở dòng «active mods» hay không. Gõ/ruflođể mở console. - Thử một việc nhỏ: trong console, vào Settings → Claude control và chọn write + ask. Rồi bảo 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 khi console hỏi. Nếu mục Missions có mục tiêu đó và Overview ghi lại hành động, nghĩa là cầu nối hoạt động. README nhấn mạnh: tạo mission không có nghĩa tính năng dark mode đã được viết.
Tư liệu chưa mô tả một dòng chữ «thành công» cố định ở terminal sau init, nên mình không hứa một thông báo cụ thể nào.
V.Dùng vào việc thật
A.Dev nhận lại một dự án lạ
Bạn mới vào một dự án cũ, không biết đâu là chỗ dễ hỏng. Sau khi init và mở lại Claude Code, dán câu mẫu:
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 theo README: agent chỉ ra module rủi ro nhất, viết test cho nó và có bản tóm tắt thay đổi. Bạn vẫn cần tự đọc lại test trước khi dùng.
Bạn không cần học 406 công cụ. Cài xong, cứ dùng Claude Code như thường, phần điều phối để ruflo lo.
Ông T
B.Người quản lý muốn nhìn rõ agent đang làm gì
Bạn giao việc cho AI nhưng không biết nó đang chạy gì, tốn bao nhiêu token. Cài ruflo-console bằng plugin, mở /ruflo. Bạn xem được workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code, mở log để xem kết quả và dò lỗi. Với người không đọc code, đây là chỗ dễ hiểu nhất của ruflo.
C.Giao quyền có kiểm soát
Bạn muốn Claude tự thao tác trong console nhưng không muốn nó làm bừa. Vào Settings → Claude control, chọn write và duyệt ask. Mỗi hành động tạo mới sẽ hỏi bạn. Nếu thấy không ổn, bấm Take back control để dừng ngay. README nói sau khi lấy lại quyền, lời gọi tiếp theo của Claude sẽ bị từ chối cho tới khi bạn khôi phục.
D.Nối Codex hoặc client MCP khác
Bạn dùng Codex thay vì Claude Code. Cấu hình client chạy npx với tham số ["-y", "ruflo@latest", "mcp", "start"]. Khi đó client của bạn dùng được các công cụ MCP của ruflo mà không cần cài vào dự án. Tư liệu không cho ví dụ kết quả cụ thể cho Codex, nên bạn tự thử bằng một việc nhỏ trước.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx báo lỗi hoặc không chạy. Rất có thể Node của bạn cũ. ruflo yêu cầu Node từ 20.0.0 trở lên. Kiểm tra bằng node --version rồi nâng cấp Node nếu cần.
Claude Code không thấy gì sau init. README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy thoát hẳn và mở lại trong đúng thư mục đã chạy init.
Lệnh /plugin không nhận hoặc cài plugin thất bại. Đườ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 /reload-plugins.
Plugin chạy hai lần, lệnh bị trùng. README cảnh báo với các plugin bên ngoài như agentic-qe-fleet, agentdb, agentic-flow: chỉ cài từ một kho duy nhất. Bật từ cả hai kho thì mod và lệnh nạp hai lần.
Claude từ chối hành động trong console. Đây không phải lỗi: hành động vượt mức quyền bạn chọn sẽ bị từ chối. Nếu thật sự cần, hãy nâng mức quyền một cách có ý thức. Hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần xác nhận.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh (một lệnh), giấy phép MIT, nhiều lựa chọn (CLI, plugin, MCP, console độc lập), có lớp kiểm soát quyền khá rõ, và repo vẫn được cập nhật trong 3 tháng gần đây. Phần console giúp người không chuyên nhìn thấy agent đang làm gì.
Giới hạn. Repo rất lớn: hàng trăm công cụ, hàng chục plugin, nhiều khái niệm như swarm, federation, vector RAG. Người mới dễ choáng. README cũng tự thừa nhận vài điểm: vòng học là khái niệm, các bản demo dùng dữ liệu mẫu và không chứng minh việc swarm đã hoàn thành công việc thật. Bản CLI thêm khá nhiều file vào dự án, còn bản plugin thì ít tính năng hơn. Các mod không bị sandbox.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời vài câu hỏi hay sửa một file nhỏ, bạn chưa cần ruflo. Nếu thích thử nhẹ nhàng, hãy chỉ cài ruflo-core bằng plugin trước, hoặc chạy trên một dự án thử. Khi thấy hữu ích mới chuyển sang npx ruflo@latest init đầy đủ.
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 bạn dùng mã nguồn tự do. Tư liệu chưa nói về chi phí của các dịch vụ đi kèm như Claude Code hay nhà cung cấp mô hình AI. Plugin ruflo-cost-tracker giúp theo dõi token và đặt ngân sách.
ruflo cần cài gì trước?
Cần Node.js từ 20.0.0 trở lên và một client như Claude Code hoặc Codex. Nếu cài plugin trong Claude Code thì cần bản 2.1.287 trở lên. Tư liệu chưa nêu yêu cầu về phần cứng hay GPU.
Cài ruflo như thế nào là nhanh nhất?
Mở terminal trong thư mục dự án và chạy npx ruflo@latest init, rồi mở lại Claude Code. Lệnh này thêm agent, hooks, bộ nhớ và máy chủ MCP vào dự án. Nếu không muốn thêm file, bạn có thể cài plugin bằng lệnh /plugin trong Claude Code.
ruflo có dùng được với Codex 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ới arguments là ["-y", "ruflo@latest", "mcp", "start"]. Chỗ điền cấu hình tuỳ client, tư liệu chưa hướng dẫn chi tiết.
Claude có tự ý làm bừa trong console ruflo không?
Không nếu bạn giữ cài đặt mặc định. Mức mặc định hiện là read + ask. Hành động vượt mức quyền bị từ chối, còn hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận. Bạn có thể bấm Take back control để dừng ngay.
ruflo khác gì dùng Claude Code thuần?
Claude Code thuần là mô hình cộng công cụ cơ bản. ruflo thêm lớp harness bên ngoài: nhiều agent chuyên biệt, swarm, bộ nhớ qua các phiên, hooks tự định tuyến, console theo dõi và kho plugin. Tư liệu chưa có số liệu so sánh hiệu quả cụ thể.
Các mod của ruflo có an toàn không?
README cảnh báo mod chạy với quyền tài khoản của bạn và không bị sandbox, nên cần đọc mã trước khi cài. Về dữ liệu, tư liệu nói federation cho phép agent trên các máy nói chuyện mà không làm lộ dữ liệu, nhưng chưa có thêm chi tiết kiểm chứng.


