Ruflo: điều phối nhiều 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 (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code hoặc Codex để thêm agent chuyên biệt, bộ nhớ qua các phiên, hook và MCP server. Bạn dùng nó để giao việc cho cả một nhóm agent phối hợp thay vì chỉ một AI. Cài khá đơn giản: 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" mã nguồn mở: lớp công cụ đặt quanh Claude Code hoặc Codex để AI không chỉ viết code mà còn có thêm agent chuyên biệt, bộ nhớ, vòng lặp tự cải thiện và các lớp kiểm soát. Repo này ban đầu có tên Claude Flow, sau đó đổi sang Ruflo. Hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.
Vấn đề nó giải quyết khá quen thuộc. Khi dùng Claude Code, bạn thường giao việc cho một AI duy nhất, mỗi phiên làm việc bắt đầu lại từ đầu, và không có công cụ nào cho bạn thấy AI đang làm gì, tốn bao nhiêu token. Ruflo thêm phần "hệ thần kinh" cho Claude Code: nhiều agent có thể chia việc theo nhóm (swarm), ghi nhớ kinh nghiệm giữa các phiên, và có bảng điều khiển để bạn theo dõi.
Ai nên dùng? 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ư rà soát cả repo, viết test, ghi lại thay đổi. Người mới cũng thử được, vì README nói rõ bạn không cần học hết hàng trăm công cụ bên trong: sau init, cứ dùng Claude Code như bình thường, phần còn lại chạy ngầm. Điểm đáng giá nhất là cách cài chỉ một lệnh, kèm lựa chọn cài dạng plugin không để lại file nào trong dự án.
ruvnet/ruflo
Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, swarm và MCP server chỉ với một lệnh init.
I.Ruflo làm được gì
README mô tả Ruflo bằng công thức "Agent = Model + Harness": model viết, còn harness cung cấp công cụ, bộ nhớ, vòng lặp, sandbox và kiểm soát để model làm việc thật. Ruflo là phần harness đó. Dưới đây là các nhóm tính năng chính, giải thích theo lợi ích thực tế.
Nhiều agent chuyên biệt, làm việc theo nhóm. README nhắc tới hơn 100 agent chuyên biệt (bảng so sánh cài đặt ghi 98 agent). Bạn có thể yêu cầu một "swarm" xử lý một việc lớn, ví dụ tìm module rủi ro nhất, viết test, rồi tóm tắt thay đổi. Lợi ích: việc lớn được chia nhỏ thay vì dồn hết vào một cuộc hội thoại dài.
Bộ nhớ qua các phiên. Ruflo có bộ nhớ tự học và tích hợp tìm kiếm vector (RAG). Agent nhớ được kinh nghiệm từ các task trước, nên bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở phiên mới. README có lưu ý trung thực: phần học này là mô hì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 cấu hình.
Hook tự định tuyến. Sau init, hệ thống hook tự chọn cách xử lý task, học từ các mẫu thành công và điều phối agent ngầm. Bạn không phải gọi từng công cụ bằng tay.
MCP server. Ruflo đi kèm MCP server nên Codex hoặc bất kỳ client MCP nào cũng nối vào được. README ghi có 406 công cụ MCP và 61 lệnh CLI, nhưng bạn không cần nhớ chúng.
Bảng điều khiển (console) ngay cạnh Claude Code. Bạn theo dõi workflow, agent, model, token và chi phí; mở log và kết quả của từng lần chạy; tìm kiếm, xem lại, so sánh. Có thể mở bằng lệnh /ruflo trong Claude Code, hoặc chạy riêng trong terminal bằng npx ruflo tui.
Cho Claude điều khiển bảng điều khiển, nhưng bạn đặt giới hạn. Trong Settings có mục Claude control với các mức read, write, manage, full, và chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask. Các hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận kể cả khi để auto.
48 plugin theo nhóm. Ví dụ ruflo-swarm (phối hợp nhiều agent), ruflo-testgen (tìm test còn thiếu và tạo test), ruflo-security-audit (quét lỗ hổng), ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí), ruflo-docs (tạo và duy trì tài liệu), ruflo-rag-memory (truy xuất thông minh). Bạn chỉ cài cái mình cần.
Federation. Agent trên các máy khác nhau có thể trao đổi an toàn với nhau. Tính năng này dành cho người dùng nâng cao, người mới chưa cần quan tâm.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js 20.0.0 trở lên.
package.jsoncủa repo yêu cầu>=20.0.0, và lệnh cài dùngnpxđi kèm Node. - Claude Code nếu bạn đi theo đường chính (README hướng dẫn mở Claude Code trong cùng thư mục dự án sau khi
init). Với Codex hoặc client MCP khác, bạn nối vào MCP server của Ruflo. - Claude Code phiên bản 2.1.287 trở lên nếu muốn cài theo kiểu plugin (marketplace). Lệnh
claude plugin installtừ terminal cần phiên bả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ói rõ về hệ điều hành, yêu cầu GPU hay dung lượng ổ đĩa, và README phần được cung cấp cũng chưa nói về API key riêng. Phần nào cần key thì bạn xem thêm trong tài liệu của repo (thư mục docs/ và file CLAUDE.md).
Mods của Ruflo chạy với quyền của tài khoản bạn và không nằm trong sandbox. README khuyên đọc code trước khi cài. Ngoài ra hãy giữ Claude control ở mức mặc định (read + ask) cho tới khi bạn hiểu rõ nó làm gì.
III.Cài đặt từng bước
README đưa ra ba đường: cài vào dự án bằng npx (đường chính), cài plugin cho Claude Code (không thêm file vào dự án), và nối MCP cho Codex hoặc client khác. Mình đi theo đường chính trước.
- Kiểm tra NodeChạy node -v và chắc chắn là 20 trở lên
- Mở terminal trong thư mục dự ánĐứng đúng thư mục bạn muốn thêm Ruflo vào
- Chạy initnpx ruflo@latest init để 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 việc thậtGõ một yêu cầu dùng swarm để rà soát repo
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 -vNếu kết quả bắt đầu bằng v20 hoặc cao hơn là ổn. Nếu thấp hơn, bạn cần nâng Node trước, vì package.json của Ruflo yêu cầu Node từ 20.0.0.
B.Mở terminal đúng thư mục dự án
Đây là chỗ người mới hay vấp nhất. Lệnh init thêm file vào thư mục hiện tại, nên bạn phải đứng đúng thư mục dự án của mình. Ví dụ:
cd duong-dan-toi-thu-muc-du-an-cua-banThay phần sau cd bằng đường dẫn thật tới dự án của bạn.
C.Chạy lệnh init
Đây là lệnh chính theo README:
npx ruflo@latest initnpx tải và chạy Ruflo bản 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 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 như .claude/, .claude-flow/ và file CLAUDE.md trong workspace. Nếu bạn thích cài theo kiểu hỏi đáp từng bước, README có lệnh:
npx ruflo@latest init wizardD.Mở Claude Code và giao việc
Mở Claude Code trong chính thư mục vừa chạy init. README cho biết Claude Code sẽ nhận các thành phần này ở lần khởi động kế tiếp, nên nếu Claude Code đang mở sẵn, hãy đóng và mở lại. Sau đó thử một yêu cầu thật, đây là prompt 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: cài dạng plugin cho Claude Code
Nếu bạn không muốn thêm file nào vào dự án, README có đường plugin. Đường này cài công cụ lõi, bảng điều khiển và các mod, và không thêm file vào dự án. Gõ các lệnh sau bên 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 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/rufloLưu ý từ README: đường plugin nhẹ hơn, chủ yếu cho slash command và định nghĩa agent. Muốn có toàn bộ vòng làm việc (98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon) thì dùng npx ruflo@latest init.
F.Cách khác: Codex hoặc client MCP
Với Codex hoặc client MCP khác, README hướng dẫn cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Hoặc bạn chạy trực tiếp:
npx -y ruflo@latest mcp startCách ghi cấu hình này vào từng client cụ thể (tên file, vị trí) README phần được cung cấp chưa nêu; bạn xem tài liệu của client bạn dùng.
IV.Kiểm tra đã chạy được chưa
Có vài dấu hiệu theo README để biết cài thành công:
- Lệnh
npx ruflo@latest initchạy xong mà không báo lỗi, và trong thư mục dự án xuất hiện các thư mục như.claude/và.claude-flow/cùng fileCLAUDE.md. - Sau khi mở lại Claude Code, bạn gõ
/ruflovà thấy bảng điều khiển (cockpit) hiện ra. - Với đường plugin, mở
/pluginvà kiểm tra các mod có xuất hiện ở dòng "active mods". - Muốn thử không cần Claude Code, chạy giao diện terminal độc lập:
npx ruflo tuiThêm --plain nếu bạn muốn in ra một khung hình duy nhất, tiện cho script.
Bài thử có kiểm chứng rõ ràng nhất trong README là tạo một "mission". Vào Settings → Claude control, chọn write + ask, rồi yêu cầu Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status." Bạn xác nhận hành động tạo, sau đó kiểm tra mục Missions có mục tiêu đó và Overview có ghi lại hành động. README nhấn mạnh: tạo mission không có nghĩa tính năng đã được làm xong.
V.Dùng vào việc thật
Phần này mình bám đúng những gì README mô tả. Kết quả thực tế sẽ tuỳ dự án và model bạn dùng.
A.Lập trình viên rà soát một repo lạ
Bạn vừa nhận một dự án cũ, không ai nhớ module nào dễ hỏng. Sau khi init và mở lại Claude Code, bạn dán prompt 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 dùng nhóm agent để chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt các thay đổi. Bạn vẫn nên đọc lại test được sinh ra trước khi chấp nhận, vì AI có thể viết test chưa sát thực tế.
Agent = Model + Harness: model viết, còn harness cho nó công cụ, bộ nhớ và giới hạn để làm việc thật.
Ông T
B.Trưởng nhóm muốn theo dõi chi phí và tiến độ
Bạn làm việc với Claude Code hằng ngày và muốn biết agent nào đang chạy, tốn bao nhiêu token. Cài đường plugin rồi mở console bằng /ruflo. Theo README, console cho bạn theo dõi workflow, agent, model, token và chi phí cạnh Claude Code, đồng thời mở log, tìm kiếm và so sánh các lần chạy. Nếu cần cảnh báo 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ài bằng cú pháp /plugin install <tên>@ruflo giống các plugin khác.
C.Người mới thử cho Claude điều khiển bảng điều khiển có kiểm soát
Bạn chưa quen với agent tự chạy và muốn thử an toàn. Làm theo kịch bản README: đặt Claude control ở mức write + ask, yêu cầu tạo một mission "add a dark mode toggle", rồi tự bấm xác nhận khi console hỏi. Muốn dừng ngay, bấm Take back control; README nói sau đó mọi lời gọi công cụ console của Claude sẽ bị từ chối cho tới khi bạn khôi phục quyền. Kết quả: bạn thấy rõ ranh giới "Claude được làm gì, bạn duyệt gì" trước khi cho nó nhiều quyền hơn.
D.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 và vẫn muốn có bộ nhớ và điều phối agent của Ruflo. Cấu hình server MCP với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Khi đó công cụ của bạn gọi được các công cụ MCP của Ruflo mà không cần thiết lập dự án. README có nhắc cả hướng Grok Build (npx ruflo init --grok, có thể thêm --dry-run để xem trước), nhưng đó là phần nâng cao, bạn đọc thêm hướng dẫn riêng trong repo.
VI.Lỗi hay gặp và cách xử lý
Báo lỗi khi chạy npx hoặc có hành vi lạ. Nguyên nhân dễ gặp nhất là Node cũ. Chạy node -v; nếu thấp hơn 20 thì nâng Node rồi chạy lại. Đây là yêu cầu có trong package.json.
Mở Claude Code nhưng không thấy gì mới. README nói Claude Code nhận agent, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Hãy đóng hẳn Claude Code rồi mở lại, và chắc chắn bạn mở nó trong đúng thư mục đã chạy init. Nếu chạy init nhầm thư mục, các file đã nằm sai chỗ, bạn nên kiểm tra thư mục đó trước khi dọn.
Lệnh /plugin không chạy hoặc không tìm thấy plugin. Đường plugin cần Claude Code 2.1.287 trở lên (lệnh claude plugin install từ terminal cần 2.1.292 trở lên). Hãy nâng Claude Code, rồi gõ /reload-plugins sau khi cài.
Plugin bị nạp hai lần. 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 duy nhất (hoặc marketplace gốc của plugin, hoặc ruflo). Cài từ cả hai thì mod và lệnh bị nạp hai lần. Hãy gỡ một bên.
Claude bị từ chối khi điều khiển console. Đây thường là thiết kế chứ không phải lỗi: mức mặc định là read + ask, và các hành động vượt quyền, hay liên quan mạng, chi tiêu, phá huỷ, đều bị từ chối hoặc đòi xác nhận. Nếu bạn cần cho phép thêm, hãy tăng mức quyền từng nấc trong Settings → Claude control, và đọc nhật ký hành động trực tiếp. Nếu bạn đã bấm Take back control thì phải khôi phục quyền mới dùng lại được.
VII.Có nên dùng không
Điểm mạnh. Cài đặt gọn: một lệnh npx ruflo@latest init là đủ để bắt đầu. Có đường nhẹ hơn là plugin không thêm file vào dự án. Hệ sinh thái rộng (48 plugin, MCP server, bảng điều khiển, bộ nhớ), giấy phép MIT, dự án vẫn được cập nhật trong vài tháng gần đây, và cộng đồng lớn. README cũng khá thẳng thắn về giới hạn, ví dụ ghi rõ các đoạn demo dùng dữ liệu mẫu và không chứng minh swarm đã hoàn thành việc thật.
Giới hạn. Ruflo khá đồ sộ: hàng trăm công cụ MCP, hàng chục lệnh và plugin, nên người mới dễ choáng nếu cố tìm hiểu hết. Nó bổ sung các tầng như hook, daemon, file cấu hình vào dự án, nên bạn cần xem lại những gì init thêm. Mod chạy với quyền tài khoản của bạn và không có sandbox. Phần học của agent là khái niệm, không nên kỳ vọng nó tự thông minh lên thần kỳ. Tư liệu tôi có chưa nêu chi phí API, yêu cầu phần cứng hay hỗ trợ từng hệ điều hành, nên bạn tự kiểm tra trước khi triển khai nghiêm túc.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần một AI hỗ trợ viết code đơn giản, Claude Code hoặc Codex đứng một mình là đủ, không cần thêm harness. Nếu chỉ cần một tính năng riêng như quét bảo mật hay sinh test, hãy cài đúng một plugin thay vì toàn bộ. Còn nếu bạn muốn thử giao việc lớn cho một nhóm agent, có bảng điều khiển để giám sát và đặt giới hạn rõ ràng, Ruflo là một lựa chọn đáng thử. Cứ bắt đầu từ đường nhẹ nhất, mức quyền thấp nhất, rồi nới dầ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 miễn phí. Tuy nhiên tư liệu chưa nói về chi phí của Claude Code, Codex hay các nhà cung cấp AI mà Ruflo gọi tới, nên bạn cần tự kiểm tra gói dịch vụ bạn đang dùng. Ruflo có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.
Ruflo cần phiên bản Node nào?
package.json của repo yêu cầu Node từ 20.0.0 trở lên. Bạn kiểm tra bằng lệnh node -v. Nếu thấp hơn, hãy nâng Node trước khi chạy npx ruflo@latest init.
Cài Ruflo có làm thay đổi dự án của tôi không?
Có, nếu dùng npx ruflo@latest init. README ghi lệnh này thêm các thư mục như .claude/, .claude-flow/ và file CLAUDE.md cùng hook, MCP server vào dự án. Nếu không muốn thêm file nào, README có đường cài plugin cho Claude Code với "zero file" trong workspace, nhưng bộ tính năng ít hơn.
Dùng được với Codex hoặc công cụ khác ngoài Claude Code không?
Được. README nói Codex và các client MCP khác dùng được bằng cách cấu hình command npx với arguments ["-y", "ruflo@latest", "mcp", "start"]. Chi tiết cách nhập cấu hình vào từng công cụ thì tư liệu chưa ghi, bạn xem tài liệu của công cụ đó.
Claude có tự ý làm những việc nguy hiểm không?
README mô tả cơ chế giới hạn: Claude control có các mức read, write, manage, full và chế độ duyệt ask hoặc auto, mặc định là read + ask. Hành động vượt quyền bị từ chối, còn hành động liên quan mạng, chi tiêu hoặc phá huỷ cần xác nhận kể cả ở chế độ auto. Bạn có thể bấm Take back control để dừng. Riêng các mod thì README cảnh báo chúng chạy với quyền tài khoản của bạn, không có sandbox.
Ruflo có chạy được trên Windows và cần GPU không?
Tư liệu tôi có chưa nêu rõ hỗ trợ hệ điều hành hay yêu cầu GPU. Điều chắc chắn là cần Node 20 trở lên và lệnh cài dùng npx. Bạn nên xem thêm tài liệu trong thư mục docs/ của repo hoặc tự thử trên máy mình.
Ruflo khác gì dùng Claude Code đơn thuần?
Claude Code là công cụ để AI viết code. Ruflo là lớp harness bao quanh nó, thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook định tuyến, MCP server và bảng điều khiển theo dõi token và chi phí. Nếu bạn chỉ cần trợ lý code đơn giản, Claude Code một mình có thể là đủ.


