ruflo: điều phối nhóm 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 (tiền thân 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ớ và có giới hạn an toàn. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node từ bản 20 trở lên. Với người mới, phần cài không khó, nhưng repo rất rộng nên nên bắt đầu từ một tác vụ nhỏ.
ruflo là một "agent harness": lớp công cụ đặt quanh Claude Code và Codex để AI không chỉ trả lời từng câu mà còn làm việc theo nhóm, nhớ lại việc cũ và chịu sự kiểm soát của bạn. Repo này trước đây có tên Claude Flow. Hiện có khoảng 81.600 sao và 9.600 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.
Tư liệu của tác giả giải thích bằng một công thức dễ nhớ: agent = mô hình + harness. Mô hình lo việc viết, còn harness cấp công cụ, bộ nhớ, vòng lặp và các giới hạn để mô hình làm việc được trong thực tế. ruflo đóng vai harness đó. Nó thêm hàng trăm agent chuyên biệt, cơ chế chia nhóm (swarm), bộ nhớ qua các phiên làm việc và các lớp bảo vệ.
Ai nên dùng? Lập trình viên đang dùng Claude Code hoặc Codex và muốn giao những việc nhiều bước như rà soát repo, viết test hay tóm tắt thay đổi. Người làm kinh doanh hoặc văn phòng có thể thử, nhưng bạn cần quen mở terminal. Điểm đáng giá nhất là ruflo cài được bằng một lệnh, rồi bạn cứ dùng Claude Code như bình thường. Phần phân tuyến tác vụ và phối hợp agent chạy nền.
ruvnet/ruflo
ruflo là bộ khung điều phối cho Claude Code và Codex: thêm agent, bộ nhớ, hook và máy chủ MCP vào dự án chỉ với một lệnh npx.
I.ruflo làm được gì
Theo README, bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Sau khi chạy init, hệ thống hook tự định tuyến tác vụ, học từ những mẫu làm việc thành công và điều phối agent ở nền. Dưới đây là các nhóm tính năng đáng chú ý nhất.
- Nhóm agent (swarm). Thay vì một AI làm tất cả, nhiều agent chia việc cho nhau. Lợi ích là các việc lớn như "rà soát cả repo" được chia nhỏ và kiểm tra chéo.
- Bộ nhớ qua nhiều phiên. Agent nhớ lại kinh nghiệm từ lần trước, nên bạn đỡ phải giải thích lại bối cảnh dự án. README lưu ý phần học này là quy trình khái niệm. Việc 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ấu hình.
- Hai đường cài đặt. Một là cài đầy đủ qua
npx ruflo init. Hai là chỉ cài plugin cho Claude Code, không thêm file nào vào dự án. - Bảng điều khiển (console). Một "buồng lái" cạnh Claude Code để theo dõi workflow, agent, mô hình, token và chi phí, xem lại từng lần chạy, tìm lỗi và so sánh. Mở bằng lệnh
/ruflo. - Cho Claude lái, bạn đặt giới hạn. Trong Settings bạn bật Claude control và chọn mức
read,write,managehoặcfull, cùng chế độ phê duyệtaskhoặcauto. Mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận, kể cả khi bậtauto. - Kho plugin. README liệt kê 48 plugin, chia theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), kiểm thử (testgen, browser), bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker)... Bạn lấy đúng cái cần dùng.
- Liên kết máy (federation). Agent trên các máy khác nhau có thể giao tiếp với nhau, theo mô tả là không làm lộ dữ liệu.
- Kết nối nhiều công cụ. Ngoài Claude Code, ruflo chạy được với Codex và các client MCP khác. README cũng có lệnh riêng cho Grok Build.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu một số điều kiện rõ ràng:
- Node.js từ bản 20.0.0 trở lên. Đây là yêu cầu trong
package.json. - Claude Code nếu bạn đi đường plugin: cần bản 2.1.287 trở lên. Muốn cài plugin từ terminal bằng lệnh
claude plugin installthì cần bản 2.1.292 trở lên. - Một thư mục dự án để chạy
init. README ghi rõ là chạy trong thư mục dự án của bạn. - Codex hoặc client MCP khác (không bắt buộc) nếu bạn không dùng Claude Code.
Về hệ điều hành, API key hay phần cứng (GPU, RAM), phần README mình có chưa nói rõ. Mình không đoán thay. Bạn xem thêm trong thư mục docs/ của repo và hướng dẫn người dùng mà README trỏ tới. Lưu ý là bản thân ruflo chạy trên nền Claude Code hoặc Codex, nên bạn cần tài khoản hoặc quyền truy cập cho công cụ AI mà bạn dùng.
Các plugin kiểu "mods" chạy với đúng quyền tài khoản của bạn và không bị cô lập (sandbox). README khuyên đọc mã nguồn trước khi cài. Với agent chạy tự động, hãy giữ mức quyền thấp (read + ask) cho đến khi bạn hiểu rõ nó làm gì.
III.Cài đặt từng bước
README có ba đường: cài đầy đủ vào dự án, chỉ cài plugin cho Claude Code, hoặc nối qua MCP cho Codex. Người mới nên chọn đường thứ nhất.
- Kiểm tra NodeChạy `node --version`, cần từ 20 trở lên
- Mở terminal trong dự áncd vào thư mục dự án của bạn
- Chạy initnpx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP
- Mở lại Claude CodeMở Claude Code ở cùng thư mục để nó nạp cấu hình
- Giao một tác vụ thậtGõ một yêu cầu mẫu, hoặc gõ /ruflo mở bảng điều khiển
A.Kiểm tra phiên bản Node
Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) và chạy:
node --versionNếu số đầu tiên nhỏ hơn 20, bạn cần cập nhật Node trước, vì package.json yêu cầu Node 20 trở lên.
B.Chạy init trong thư mục dự án
Đây là chỗ người mới hay vấp nhất: bạn phải đứng đúng thư mục dự án trước khi chạy lệnh. Thay đường dẫn bằng thư mục của bạn.
cd duong-dan-toi-du-an-cua-ban
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và máy chủ MCP của ruflo vào dự án. README mô tả các file được thêm gồm .claude/, .claude-flow/, CLAUDE.md, các file helper và settings. Nếu bạn dùng Git, hãy commit trước khi chạy để dễ xem ruflo đã thêm gì. Lần đầu npx có thể phải tải gói nên hơi lâu.
Muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh:
npx ruflo@latest init wizardC.Mở Claude Code và giao việc
Mở Claude Code ở đúng thư mục đó. README nói Claude Code sẽ nhận các thành phần mới ở lần khởi động kế tiếp. Rồi thử một tác vụ thật, ví dụ câu mẫu trong README:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.D.Cách khác: chỉ cài plugin cho Claude Code
Đường này không thêm file nào vào dự án. Bạn gõ trực tiếp trong Claude Code (không phải trong terminal thường):
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/rufloNếu có 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/rufloREADME so sánh hai đường: plugin chỉ cho slash command, vài skill và định nghĩa agent, không cài hook. Cài bằng npx ruflo init mới có đầy đủ agent, lệnh, skill, máy chủ MCP, hook và daemon. README khuyên dùng đường đầy đủ cho việc nghiêm túc.
E.Cách khác: Codex hoặc client MCP khác
Trong phần cấu hình MCP của client, đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Tương đương với lệnh này:
npx -y ruflo@latest mcp startNơi dán cấu hình tuỳ từng client, bạn xem tài liệu của client đó.
F.Cách khác: chạy giao diện terminal riêng
Bảng điều khiển chạy được độc lập, 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
Theo README, dấu hiệu thành công khá rõ:
- Sau
init, bạn mở lại Claude Code ở cùng thư mục rồi gõ/ruflo. Bảng điều khiển hiện ra là cài xong. - Với đường plugin, gõ
/pluginvà xem các plugin đã cài có nằm trong dòng "active mods" không. - Trong thư mục dự án có thêm
.claude/,.claude-flow/vàCLAUDE.md(với đườnginit). - Thử bài mẫu của README: bật Settings → Claude control → write + ask, rồi yêu cầu "Create a mission to add a dark mode toggle. Show me the mission and its status." Claude sẽ mở mục Missions và hỏi bạn xác nhận tạo. Sau đó bạn thấy mục tiêu nằm trong Missions và hành động được ghi ở Overview.
Lưu ý README nói rõ: tạo mission không có nghĩa là tính năng đã được viết xong. Nó chỉ là bản ghi mục tiêu.
V.Dùng vào việc thật
Bám đúng những gì README mô tả, đây là vài tình huống bạn thử được ngay.
A.Dev rà soát một repo lạ
Bạn nhận một dự án cũ và không biết chỗ nào dễ hỏng. Sau khi init, mở Claude Code trong thư mục dự án và dán đúng 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.Bạn nhận lại một báo cáo ngắn: module rủi ro nhất, các test mới và phần tóm tắt thay đổi. Hãy đọc kỹ các test trước khi gộp vào nhánh chính.
Bạn vẫn dùng Claude Code như cũ, ruflo lo phần chia việc ở phía sau.
Ông T
B.Trưởng nhóm theo dõi chi phí và tiến độ
Bạn muốn biết AI đang làm gì và tốn bao nhiêu. Cài ruflo-console, mở /ruflo và xem workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Khi một lần chạy lỗi, bạn mở log của agent để tìm nguyên nhân và so sánh với lần trước. Nếu muốn theo dõi ngân sách, README có plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí).
C.Người dùng Codex hoặc công cụ MCP khác
Bạn không dùng Claude Code mà dùng Codex. Cấu hình MCP với command npx và arguments như ở trên. Máy chủ ruflo sẽ cung cấp công cụ điều phối cho client của bạn mà không cần chạy init cho cả dự án.
D.Nhóm nhỏ chỉ muốn thử một vài kỹ năng
Bạn chưa muốn thêm file vào dự án. Hãy cài vài plugin riêng, ví dụ ruflo-testgen (tìm test còn thiếu và tạo tự động) hoặc ruflo-docs (tạo và duy trì tài liệu). Bạn dùng thử các lệnh của riêng plugin đó. Nếu thấy hợp, chuyển sang cài đầy đủ sau.
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ũ. Chạy node --version, nếu nhỏ hơn 20 thì cập nhật Node rồi chạy lại.
Mở Claude Code nhưng không thấy ruflo. README nói Claude Code nhận thành phần mới ở lần khởi động kế tiếp. Hãy đóng hẳn rồi mở lại, và chắc chắn bạn mở đúng thư mục đã chạy init. Với đường plugin, chạy /reload-plugins rồi /plugin để kiểm tra.
Lệnh /plugin không có hoặc cài plugin thất bại. Đường plugin yêu cầu Claude Code 2.1.287 trở lên (2.1.292 nếu cài từ terminal bằng claude plugin install). Hãy cập nhật Claude Code trước.
Plugin hoạt động hai lần. Với các plugin bên 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 nơi, mod và lệnh của chúng sẽ bị nạp hai lần.
Claude từ chối một thao tác trong bảng điều khiển. Đây là hành vi đúng. Thao tác vượt mức quyền bạn đặt sẽ bị từ chối, và các thao tác liên quan mạng, chi tiêu hoặc phá huỷ luôn cần xác nhận. Nếu muốn dùng, hãy nâng mức quyền một cách có chủ đích. Muốn dừng hẳn, bấm Take back control.
Không thấy kết quả như kỳ vọng sau khi giao việc. README nhắc rằng các demo mẫu dùng dữ liệu mẫu và không chứng minh việc hoàn thành swarm hay khả năng nhớ lại. Hãy bắt đầu với một tác vụ nhỏ, kiểm tra kết quả bằng chính mắt bạn và đừng giao việc lớn ngay từ đầu.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Không bắt bạn học hết bộ công cụ vì hook tự chạy ở nền. Có nhiều đường vào (init đầy đủ, plugin nhẹ, MCP cho Codex, giao diện terminal) và có bảng điều khiển để theo dõi chi phí, log. Cơ chế giới hạn quyền (read/write/manage/full, ask/auto) giúp bạn giữ quyền kiểm soát. Giấy phép MIT và repo vẫn được cập nhật trong ba tháng gần đây.
Giới hạn. Repo rất lớn: hàng trăm công cụ, 48 plugin, cộng với nhiều khái niệm mới như swarm, federation, bộ nhớ vector. Người mới dễ bị choáng. Lệnh init thêm khá nhiều file vào dự án. Phần "tự học" được README tự mô tả là mô hình khái niệm. Các demo dùng dữ liệu mẫu, nên bạn cần tự kiểm chứng trên việc của mình. Về yêu cầu API key, hệ điều hành hay phần cứng, phần README mình có chưa nói rõ.
Khi nào chọn cách khác. Nếu bạn chỉ cần một trợ lý viết code đơn giản, dùng Claude Code hoặc Codex thuần là đủ. Nếu muốn thử nhẹ mà không đụng vào dự án, hãy cài từng plugin. Nếu bạn không đọc được code và chưa có ai rà soát giúp, đừng cho agent chạy tự động ở mức quyền cao. Hãy bắt đầu ở mức đọc, dần dần nâng lên.
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 và cài qua npx. Tuy nhiên ruflo chạy trên Claude Code, Codex hoặc các nhà cung cấp AI khác, nên chi phí dùng các công cụ đó là chuyện riêng. Tư liệu mình có không nêu giá cụ thể.
Cần GPU hay máy cấu hình mạnh không?
Tư liệu mình có không nói về yêu cầu phần cứng. Điều kiện duy nhất được nêu rõ là Node.js từ bản 20 trở lên. Một số plugin như ruflo-ruvector nhắc tới tìm kiếm tăng tốc GPU, nhưng đó là plugin riêng, không phải bắt buộc.
Dùng được cho Codex hay chỉ riêng Claude Code?
Dùng được cả hai. README nói Codex và các client MCP khác hoạt động khi bạn cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Repo còn có lệnh riêng `npx ruflo init --grok` cho Grok Build.
Cài plugin và chạy init khác nhau thế nào?
Plugin không thêm file nào vào dự án và chỉ cho slash command, vài skill, định nghĩa agent. Còn `npx ruflo init` thêm đầy đủ agent, lệnh, skill, máy chủ MCP, hook, daemon cùng các file như `.claude/`, `.claude-flow/`, `CLAUDE.md`. README khuyên dùng `init` cho việc nghiêm túc và dùng plugin để thử nhẹ.
Cho Claude điều khiển bảng điều khiển có an toàn không?
Bạn tự đặt giới hạn: read, write, manage hoặc full, kèm chế độ ask hoặc auto. Mặc định hiện là read + ask. Thao tác vượt quyền bị từ chối, thao tác liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận, và có nút Take back control để thu lại quyền.
ruflo có chạy được trên Windows không?
Phần tư liệu mình có chưa ghi rõ hệ điều hành được hỗ trợ. Các lệnh chính đều là lệnh Node/npx. Bạn nên xem thêm trong thư mục docs của repo hoặc hướng dẫn người dùng trước khi cài.
ruflo khác gì Claude Flow?
README cho biết Claude Flow là tên cũ, nay đổi thành Ruflo. Tác giả là Reuven Cohen (rUv). Gói npm hiện vẫn hiển thị tên claude-flow, còn lệnh dùng trong README là `npx ruflo@latest init`.


