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à lớp điều phối bọc quanh Claude Code và Codex, thêm hàng chục agent chuyên biệt, bộ nhớ giữa các phiên, hook và MCP server. Bạn dùng nó để giao một việc lớn cho cả nhóm agent thay vì một agent đơn lẻ. Cài chỉ cần một lệnh npx trong thư mục dự án, với điều kiện có Node 20 trở lên.
ruflo là một bộ khung điều phối (người ta gọi là harness) đặt quanh Claude Code và Codex. Nó thêm cho các công cụ này những thứ chúng không có sẵn: nhiều agent chuyên biệt, bộ nhớ lưu giữa các 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, giấy phép MIT, viết chủ yếu bằng TypeScript.
Tác giả diễn đạt ý tưởng thế này: mô hình AI là bên viết, còn harness là bên đưa cho nó công cụ, bộ nhớ, vòng lặp và các giới hạn để nó làm việc được thật. ruflo là phần harness đó. Bạn vẫn dùng Claude Code như cũ, còn ruflo lo việc chia việc cho nhiều agent, nhớ kinh nghiệm và theo dõi kết quả.
Ai nên dùng? Chủ yếu là lập trình viên (kể cả người mới) đã quen Claude Code hoặc Codex và muốn giao việc lớn hơn, như rà soát cả một repo, viết test, theo dõi chi phí. Điểm đáng giá nhất là cài rất gọn: một lệnh npx ruflo@latest init là xong phần nền, 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 mà cứ dùng Claude Code bình thường.
ruvnet/ruflo
ruflo là bộ khung (harness) thêm agent, bộ nhớ, hook và MCP server cho Claude Code và Codex, để nhiều agent phối hợp làm việc theo nhóm.
I.ruflo làm được gì
Dưới đây là những tính năng chính theo README, giải thích theo lợi ích thực tế.
- Nhiều agent làm việc theo nhóm (swarm). README nói ruflo bổ sung hơn 100 agent chuyên biệt và cho chúng phối hợp như một đội. Với bạn, đó là cách chia một việc lớn (ví dụ rà soát repo) thành nhiều phần, mỗi agent lo một phần.
- Bộ nhớ qua nhiều phiên. Agent nhớ được kinh nghiệm từ các lần làm trước. Lần sau bạn không phải giải thích lại từ đầu. Plugin liên quan trong danh sách gồm
ruflo-agentdb,ruflo-rag-memoryvàruflo-rvf. - Hook tự định tuyến và học. Sau khi
init, hệ thống hook tự chọn hướng xử lý cho tác vụ, học từ các mẫu làm việc thành công và điều phối agent chạy ngầm. Bạn không cần gõ lệnh riêng. - Bảng điều khiển (console) ngay cạnh Claude Code. Gõ
/ruflođể xem workflow, agent, model, token và chi phí. Bạn có thể mở log và kết quả của từng lần chạy, tìm kiếm, xem lại và so sánh. - Cho Claude điều khiển console, 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ệtaskhoặcauto. Mặc định hiện là read + ask. Các hành động mạng, tốn tiền hoặc phá huỷ vẫn phải xác nhận kể cả khi đangauto. - Kho plugin. README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), 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-security-auditquét lỗ hổng,ruflo-docsviết tài liệu. - Dùng được với Codex và client MCP khác. Không riêng Claude Code. Repo cũng có hướng dẫn cho Grok Build (
npx ruflo init --grok). - Federation. Agent trên các máy khác nhau có thể liên lạc với nhau. Với người mới thì tính năng này chưa cần, bạn cứ biết là có.
II.Cần chuẩn bị gì
Chỉ liệt kê những gì tư liệu nói:
- 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, hoặc một client MCP khác) để dùng ruflo.
- Claude Code 2.1.287 trở lên nếu bạn chọn đường cài bằng plugin. Lệnh
claude plugin installngoài terminal cần bản 2.1.292 trở lên. - Một thư mục dự án để chạy
init.
Tư liệu không nêu yêu cầu phần cứng cụ thể nào, cũng không nói rõ hệ điều hành nào được hỗ trợ. Phần Windows, macOS hay Linux mình không có thông tin, bạn xem thêm trong tài liệu của repo. Bản thân Claude Code và các mô hình AI vẫn cần tài khoản hoặc khoá của riêng chúng, và README ruflo không hướng dẫn phần đó.
III.Cài đặt từng bước
README có nhiều đường cài. Đường nhanh nhất là chạy init trong dự án. Bên dưới mình trình bày đường này trước, rồi đến đường plugin và đường dành cho Codex.
- Mở terminal đúng thư mụcvào thư mục dự án của bạn
- Chạy initnpx ruflo@latest init
- Mở lại Claude Codeđể nó nạp agent, hook, bộ nhớ và MCP server
- Giao việc đầu tiêndán một câu lệnh thật vào Claude Code
- (Tuỳ chọn) Mở consolegõ /ruflo trong Claude Code
A.Mở terminal trong thư mục dự án
Đâ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 thư mục dự án trước khi chạy. Ví dụ với PowerShell:
cd duong-dan-toi-du-an-cua-banThay duong-dan-toi-du-an-cua-ban bằng đường dẫn thật của bạn.
B.Chạy lệnh init
npx ruflo@latest initnpx tải ruflo bản mới nhất và chạy. 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 cách này tạo ra các thư mục và file như .claude/, .claude-flow/, CLAUDE.md cùng các file hỗ trợ và settings. Vì vậy hãy chạy trong dự án bạn muốn thử, và nên có git để xem được những gì đã thay đổi.
Nếu muốn thiết lập có hỏi đáp từng bước, README cho phép chạy:
npx ruflo@latest init wizardBạn muốn xem trước mà chưa ghi gì thì có cờ --dry-run, nhưng README chỉ nói rõ cờ này trong phần Grok Build (npx ruflo init --grok). Với lệnh init thường, mình chưa có thông tin là cờ này có áp dụng hay không.
C.Mở lại Claude Code
Mở Claude Code ngay trong thư mục đó. README nói Claude Code sẽ nạp các thành phần mới ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code, hãy thoát rồi mở lại.
D.Giao việc đầu tiên
Dán câu mẫu của README vào Claude Code:
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 bảo Claude dùng một nhóm agent của ruflo để rà soát repo, tìm module rủi ro nhất, viết test cho nó rồi tóm tắt những gì đã đổi.
E.Đường khác: chỉ cài plugin Claude Code
Đường 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, không phải ngoài terminal:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/rufloTừng dòng làm gì: thêm kho plugin của ruflo, cài lõi, cài console và cài mods, nạp lại plugin rồi mở console. Từ terminal, trên Claude Code 2.1.292 trở lên, README ghi lệnh:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloMods chạy với quyền của tài khoản bạn và không bị đóng khung trong sandbox. README khuyên đọc mã nguồn trước khi cài. Đường plugin cũng nhẹ hơn: theo bảng so sánh, nó không cài hook, còn đường `init` mới là bộ đầy đủ.
F.Đường khác: Codex hoặc client MCP khác
Không cần thiết lập dự án. Trong phần cấu hình MCP của client, đặt command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Tức là client sẽ tự chạy lệnh npx -y ruflo@latest mcp start để khởi động MCP server của ruflo. Nơi dán cấu hình này tuỳ từng client, bạn xem tài liệu của client đó.
G.Đường khác: chạy console trong terminal thường
Console chạy được riêng, không cần Claude Code:
npx ruflo tuiThêm --plain để in ra đúng một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
README không có một lệnh kiểm tra duy nhất, nhưng có mấy dấu hiệu bạn có thể dựa vào:
- Sau
init: thư mục dự án có thêm các mục như.claude/,.claude-flow/vàCLAUDE.md(theo bảng so sánh trong README). Mở lại Claude Code thì nó nạp các thành phần mới. - Console: gõ
/ruflotrong Claude Code. Nếu bảng điều khiển hiện ra thì phần console đã hoạt động. - Plugin: mở
/pluginvà xem các mod xuất hiện trong dòng active mods. Trong console,/ruflo marketmở danh mục plugin để cài, bật, tắt và cập nhật. - Terminal UI:
npx ruflo tuimở console độc lập. - Phép thử thật: giao câu lệnh swarm mẫu ở trên và xem Claude có chạy nhóm agent, viết test và tóm tắt không.
V.Dùng vào việc thật
A.Rà soát một dự án đang có và bổ sung test
Bạn là lập trình viên mới nhận một dự án cũ, chưa rõ chỗ nào dễ hỏng. Sau khi chạy npx ruflo@latest init và mở lại Claude Code, bạn dán câu lệnh:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.Kết quả bạn nhận là một bản tóm tắt module nào rủi ro nhất, các test mới được thêm và những thay đổi đã làm. Hãy tự chạy lại test và xem diff trước khi giữ lại thay đổi nào.
Agent = Model + Harness: mô hình 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.Tạo một mission trong console và tự tay duyệt
Bạn muốn thử xem Claude điều khiển console an toàn đến đâu. Theo ví dụ của README: cài console, mở /ruflo, vào Settings → Claude control và chọn 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 mở trang Missions và đặt mục tiêu. Bạn xác nhận hành động tạo đang chờ. Sau đó kiểm tra mục Missions có mục tiêu mới chưa và Overview có ghi lại hành động chưa. README lưu ý: tạo mission không có nghĩa tính năng đã được làm. Nếu muốn dừng, bấm Take back control và các lệnh gọi sau đó của Claude sẽ bị từ chối cho đến khi bạn trả quyền.
C.Dùng ruflo từ Codex hoặc một client MCP khác
Bạn không dùng Claude Code mà dùng Codex. Bạn khai báo MCP server với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"] như phần cài đặt ở trên. Client sẽ thấy các công cụ MCP của ruflo mà không cần thêm file nào vào dự án. README không đưa ví dụ prompt riêng cho Codex, nên bạn thử với một việc nhỏ trước.
D.Theo dõi chi phí token khi chạy nhiều agent
Chạy nhiều agent đồng nghĩa với việc tiêu nhiều token. Trong danh sách plugin, ruflo-cost-tracker có chức năng theo dõi lượng token, đặt ngân sách và cảnh báo chi phí. Bạn cài theo đúng mẫu lệnh của các plugin khác:
/plugin install ruflo-cost-tracker@rufloRồi mở /ruflo để xem token và chi phí cạnh Claude Code. README không nói chi tiết cách đặt ngân sách, nên bạn xem tài liệu plugin trong repo (thư mục plugins/) để biết thêm.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx ruflo@latest init báo lỗi vì phiên bản Node. Repo yêu cầu Node từ 20.0.0 trở lên. Kiểm tra phiên bản bằng node --version và nâng cấp nếu cũ hơn.
Gõ /plugin marketplace add ... mà Claude Code không nhận. Đường plugin cần Claude Code 2.1.287 trở lên. Hãy cập nhật Claude Code. Cũng nhớ rằng các lệnh /plugin ... gõ bên trong Claude Code, không gõ ở terminal thường.
Cài xong mà không thấy agent hay hook. README nói Claude Code nạp các thành phần ở lần khởi động tiếp theo. Hãy thoát và mở lại Claude Code đúng trong thư mục đã chạy init. Với plugin, thử /reload-plugins. Cần nhớ rằng đường plugin không cài hook, nên nếu bạn cần đủ bộ thì dùng npx ruflo@latest init.
Claude từ chối thao tác trong console. Đây là tính năng chứ không phải lỗi: hành động vượt quá mức quyền bạn đặt (read, write, manage, full) sẽ bị từ chối. Mặc định là read + ask. Nếu cần tạo mission, nâng lên write + ask và tự duyệt từng bước.
Cài trùng plugin từ hai kho. 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 kho, vì bật từ cả hai thì mod và lệnh sẽ nạp hai lần.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Có sẵn rất nhiều thứ (agent, bộ nhớ, hook, console, plugin). Giấy phép MIT, repo vẫn được cập nhật trong 3 tháng gần đây. Cơ chế cấp quyền cho Claude trong console khá rõ ràng, với mức quyền và bước xác nhận.
Giới hạn. Số lượng thành phần lớn (README nhắc 406 công cụ MCP và 61 lệnh CLI) nên bạn dễ choáng lúc đầu. Lệnh init thêm khá nhiều file vào dự án. Mods không được đóng sandbox. Chạy nhiều agent có thể tốn token hơn dùng một agent. Phần học và nhớ phụ thuộc vào embeddings và các module học được cấu hình, và README tự ghi chú rằng sơ đồ vòng học chỉ là khái niệm. Các đoạn demo trong README dùng dữ liệu mẫu hoặc phát lại khung hình, chưa chứng minh được kết quả swarm thật.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code làm việc nhỏ lẻ trong một file, dùng Claude Code thuần là đủ. Nếu muốn thử nhẹ, hãy cài một hai plugin theo đường plugin trước, vì đường này không thêm file nào vào dự án. Khi thấy hữu ích mới chuyển sang init đầy đủ. Dù chọn đường nào, hãy thử trên một dự án nhỏ có git và luôn xem lại kết quả agent tạo ra trước khi dùng 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 bạn dùng và cài miễn phí. Tuy nhiên các mô hình AI chạy bên dưới (như Claude hay Codex) có chi phí riêng theo tài khoản của bạn, và README ruflo không nêu giá. Plugin ruflo-cost-tracker giúp theo dõi token và chi phí.
Cài ruflo cần những gì?
Cần Node.js từ 20.0.0 trở lên và một công cụ để dùng, như Claude Code hoặc Codex. Nếu cài theo đường plugin thì cần Claude Code 2.1.287 trở lên. Tư liệu không nêu yêu cầu phần cứng hay GPU.
ruflo khác gì dùng Claude Code thông thường?
Claude Code vẫn là nơi bạn làm việc. ruflo thêm lớp harness gồm hàng chục agent chuyên biệt, bộ nhớ qua nhiều phiên, hook tự định tuyến và console theo dõi. README nói sau khi init bạn cứ dùng Claude Code bình thường.
Dùng ruflo với Codex hoặc công cụ khác được không?
Được. README nói Codex và các client MCP khác dùng được bằng cách đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Repo cũng có hướng dẫn riêng cho Grok Build.
Lệnh init có thay đổi dự án của tôi không?
Có. Theo bảng so sánh trong README, cài bằng npx ruflo init tạo các mục như .claude/, .claude-flow/, CLAUDE.md và file hỗ trợ, đồng thời đăng ký MCP server và hook. Đường cài plugin thì không thêm file nào vào dự án, nhưng cũng không có hook.
Cho Claude điều khiển console có an toàn không?
README mô tả các lớp giới hạn: bạn chọn mức read, write, manage hoặc full, cùng chế độ duyệt ask hoặc auto. Mặc định là read + ask, và hành động liên quan mạng, chi tiền hay phá huỷ vẫn cần xác nhận kể cả khi auto. Nút Take back control dừng việc Claude điều khiển. Riêng mods thì không chạy trong sandbox nên cần đọc mã trước khi cài.
Chạy được trên Windows không?
Tư liệu mình có không nêu rõ hệ điều hành nào được hỗ trợ. Điều chắc chắn là repo yêu cầu Node 20 trở lên. Bạn nên thử trên một dự án nhỏ và xem tài liệu trong thư mục docs của repo để biết thêm.


