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 (trước đây là Claude Flow) là một 'harness' viết bằng TypeScript, đặt quanh Claude Code và Codex để thêm nhiều agent chuyên biệt, bộ nhớ lâu dài, hook tự động và bảng điều khiển. Bạn có thể cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, hoặc chỉ cài plugin trong Claude Code. Cài không khó nếu máy đã có Node 20 trở lên, nhưng công cụ rất rộng nên nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một «harness» cho các trợ lý lập trình AI: nó là lớp công cụ đặt quanh Claude Code và Codex để các trợ lý này có thêm agent chuyên biệt, bộ nhớ, vòng lặp tự động và các lớp kiểm soát. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, viết chủ yếu bằng TypeScript và dùng giấy phép MIT.
Hãy hình dung thế này: mô hình AI là người thợ giỏi, còn harness là cái bàn làm việc đầy đủ đồ nghề xung quanh. Bình thường Claude Code làm từng việc một và quên sạch khi bạn đóng phiên. Sau khi cài Ruflo, nhiều agent có thể chia việc theo kiểu «swarm» (bầy nhóm), nhớ kinh nghiệm giữa các phiên, và bạn có một bảng điều khiển để theo dõi tiến độ, token và chi phí ngay cạnh Claude Code.
Repo này hợp với lập trình viên mới, người làm kỹ thuật trong doanh nghiệp nhỏ, hoặc ai đã quen Claude Code và muốn giao những việc lớn hơn như rà soát cả repo, viết test hàng loạt. Điểm đáng giá nhất là cài chỉ bằng một lệnh, rồi bạn cứ dùng Claude Code như bình thường; hệ thống hook sẽ tự định tuyến việc và phối hợp agent ở phía sau. Hiện repo có khoảng 81.582 sao và 9.607 fork, và vẫn được cập nhật trong ba tháng gần đây.
ruvnet/ruflo
Ruflo là lớp điều phối bao quanh Claude Code và Codex: thêm agent chuyên biệt, bộ nhớ qua nhiều phiên và bảng điều khiển, cài chỉ bằng một lệnh npx.
I.Ruflo làm được gì
Theo README, Ruflo thêm vào Claude Code và Codex những khả năng sau.
- Nhiều agent chuyên biệt. README nêu hơn 100 agent. Thay vì một trợ lý làm mọi thứ, bạn có thể giao việc cho nhóm: người rà soát, người viết test, người tổng hợp.
- Swarm (bầy agent phối hợp). Các agent tự tổ chức để chia việc. Bạn chỉ cần nói «dùng một swarm của ruflo để làm việc X».
- Bộ nhớ qua nhiều phiên. Agent nhớ kinh nghiệm từ các tác vụ trước và đưa lại vào việc định tuyến. README ghi rõ phần truy xuất vector cục bộ có thể chạy 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 khi chạy
init, bạn dùng Claude Code bình thường; hook tự định tuyến tác vụ và học từ những mẫu thành công. Bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI mà README nhắc tới. - Bảng điều khiển (console). Theo dõi workflow, agent, mô hình, token và chi phí; mở log và kết quả của từng lần chạy, tìm kiếm, phát lại và so sánh. Gõ
/ruflotrong Claude Code để mở. - Claude điều khiển console trong giới hạn bạn đặt. Bạn chọn mức
read,write,managehoặcfull, cùng chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Hành động liên quan mạng, chi tiêu hay phá huỷ vẫn phải xác nhận kể cả khi đểauto. - Hệ plugin. README liệt kê 48 plugin (cộng 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, DevOps... Ví dụ
ruflo-testgentìm test còn thiếu và sinh ra,ruflo-cost-trackertheo dõi token và đặt ngân sách,ruflo-security-auditquét lỗ hổng. - Federation. Agent trên các máy khác nhau có thể trao đổi với nhau một cách an toàn, theo README là không làm rò dữ liệu.
II.Cần chuẩn bị gì
Tư liệu repo chỉ nêu rõ những điểm sau:
- 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 nếu bạn dùng cách cài vào dự án hoặc cài plugin. Riêng đường cài chỉ bằng plugin cần Claude Code 2.1.287 trở lên; lệnh
claude plugin installtừ terminal cần 2.1.292 trở lên. - Một thư mục dự án để chạy lệnh khởi tạo.
- Codex hoặc client MCP khác là tuỳ chọn, nếu bạn không dùng Claude Code.
Về hệ điều hành, tài khoản, API key hay phần cứng (GPU), phần README tôi có không nói rõ. Bạn nên xem thêm phần hướng dẫn người dùng trong thư mục docs/ của repo nếu cần.
Ruflo là lớp đặt trên Claude Code hoặc Codex, nên các dịch vụ đó vẫn dùng tài khoản và hạn mức của bạn. Nhiều agent chạy song song có thể tốn token hơn một phiên thường. Hãy mở bảng điều khiển để xem token và chi phí, và thử với việc nhỏ trước.
III.Cài đặt từng bước
Repo có ba đường cài. Đường đầu tiên là đường chính và đầy đủ nhất.
- Mở terminal trong dự ánVào đúng thư mục dự án bạn muốn dùng Ruflo
- Chạy initGõ npx ruflo@latest init để thêm agent, hook, bộ nhớ và 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 một tác vụ thậtNhờ Claude dùng swarm của ruflo làm việc cụ thể
- Mở bảng điều khiểnGõ /ruflo trong Claude Code để theo dõi
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ên Windows, bạn có thể mở thư mục đó rồi chọn mở terminal tại đây. Nếu muốn thử trên dự án trống, hãy tạo thư mục mới trước.
cd duong-dan/toi/du-an-cua-banHãy thay duong-dan/toi/du-an-cua-ban bằng đường dẫn thật. Gõ node --version để chắc chắn Node từ bản 20 trở lên.
B.Chạy lệnh init
Lệnh này theo README là cách bắt đầu bằng một lệnh:
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. Trong bảng so sánh, README còn nói cách này tạo ra .claude/, .claude-flow/, CLAUDE.md, các file hỗ trợ và settings trong thư mục của bạn. Nếu dự án đã có CLAUDE.md, bạn nên sao lưu hoặc dùng Git để xem thay đổi. Chưa thấy README nói rõ việc ghi đè xử lý thế nào.
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 và giao việc
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent, hook, bộ nhớ và MCP server ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code, hãy thoát ra mở lại. Sau đó thử một tác vụ thật; 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.Bạn có thể viết bằng tiếng Việt, nhưng nên giữ cụm «ruflo swarm» để Claude biết phải dùng công cụ nào.
D.Cách khác: chỉ cài plugin trong Claude Code
Cách này không thêm file nào vào dự án và cài lõi, bảng điều khiển và các mod. Nó cần Claude Code 2.1.287 trở lên. Gõ từng dòng 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/rufloCần hiểu rõ khác biệt: README so sánh rằng đường plugin chỉ cho lệnh slash, một ít skill và định nghĩa agent, không có hook và không để lại file trong dự án; còn npx ruflo init mới là «vòng lặp đầy đủ» (98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon) và là cách README khuyên cho dùng thật.
E.Cách khác: dùng với Codex hoặc client MCP
Không cần cài cho dự án. Trong cấu hình MCP của client, đặt command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]README cũng ghi dạng lệnh đầy đủ là npx -y ruflo@latest mcp start. Chỗ điền cấu hình này phụ thuộc client bạn dùng; xem tài liệu của client đó.
F.Cách khác: chạy bảng điều khiển ngoài Claude Code
Bảng điều khiển chạy độc lập trong terminal:
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
Theo tư liệu, bạn có thể kiểm tra theo các dấu hiệu sau:
- Sau
init, trong thư mục dự án có thêm.claude/,.claude-flow/vàCLAUDE.md. - Mở lại Claude Code, gõ
/ruflo. Bảng điều khiển hiện ra là dấu hiệu tốt nhất. - Nếu cài bằng plugin, gõ
/pluginvà xemruflo-console,ruflo-modscó nằm trong dòng mod đang hoạt động hay không. - Với
ruflo-core, công cụ MCP xuất hiện dưới tên nhưmcp__plugin_ruflo-core_ruflo__memory_store. - Chạy thử câu lệnh mẫu về swarm ở trên và xem Claude có gọi các công cụ của Ruflo không.
Một điểm trung thực mà README tự nhắc: các bản demo hoạt hình trong repo dùng dữ liệu mẫu, không phải bằng chứng một swarm đã hoàn thành việc thật. Hãy tự kiểm tra kết quả trên dự án của bạn.
V.Dùng vào việc thật
A.Rà soát một repo cũ vừa nhận bàn giao
Bối cảnh: bạn là dev mới vào công ty, nhận một dự án cũ ít test và không biết bắt đầu từ đâu.
Cách làm: chạy npx ruflo@latest init trong thư mục dự án, mở lại Claude Code rồi dán câ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ả: Claude điều các agent đi tìm module rủi ro nhất, viết test cho nó và tóm tắt phần đã đổi. Bạn đọc phần tóm tắt, chạy test và xem diff trước khi giữ lại.
Bạn vẫn viết code như cũ; Ruflo lo phần điều phối phía sau.
Ông T
B.Theo dõi chi phí và tiến độ khi giao việc dài
Bối cảnh: chủ một nhóm nhỏ làm phần mềm, muốn biết agent đang làm gì và tốn bao nhiêu token.
Cách làm: cài plugin console, rồi mở /ruflo. Bảng điều khiển hiển thị workflow, agent, mô hình, token và chi phí. Bạn có thể mở log từng lần chạy, tìm kiếm, triage lỗi, phát lại và so sánh các lần chạy. README còn có plugin ruflo-cost-tracker để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí.
Kết quả: bạn thấy rõ lần chạy nào tốn kém hoặc thất bại, thay vì chỉ biết cuối tháng.
C.Để Claude tạo «mission» trong console, nhưng bạn giữ quyền
Bối cảnh: bạn muốn thử cho Claude điều khiển bảng điều khiển mà vẫn an toàn.
Cách làm: theo các bước README mô tả: 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ở mục Missions và đặt mục tiêu; bạn xác nhận hành động tạo đang chờ. Kiểm tra mục Missions có mục tiêu mới, và mục Overview có ghi lại hành động.
Kết quả: có một mission được tạo. Lưu ý README nói rõ: tạo mission không có nghĩa tính năng đã được làm xong. Muốn dừng, bấm Take back control; lần gọi sau của Claude sẽ bị từ chối cho tới khi bạn khôi phục quyền.
D.Dùng Ruflo với Codex hoặc công cụ MCP khác
Bối cảnh: nhóm bạn dùng Codex thay vì Claude Code và chỉ muốn thêm bộ công cụ, không muốn thêm file vào dự án.
Cách làm: trong cấu hình MCP của Codex, đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"] như phần trên.
Kết quả: client có thể gọi các công cụ MCP của Ruflo. Phần README tôi có chưa mô tả chi tiết danh sách công cụ cho từng client, nên hãy xem thư mục docs/ để biết cụ thể.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh /plugin báo không tìm thấy hoặc không cài được
Đường plugin cần Claude Code từ 2.1.287 trở lên, và lệnh claude plugin install từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi thử lại; sau khi cài, gõ /reload-plugins.
B.npx báo lỗi hoặc không có lệnh npx
Thường do chưa cài Node.js, hoặc Node quá cũ. package.json yêu cầu Node từ 20.0.0 trở lên. Kiểm tra bằng node --version, cài hoặc nâng cấp rồi mở terminal mới.
C.Cài xong nhưng Claude Code không thấy agent hay công cụ
Claude Code chỉ 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. Nếu đi đường plugin, kiểm tra bằng /plugin và chạy /reload-plugins.
D.Plugin chạy hai lần hoặc lệnh bị trùng
README cảnh báo với các plugin bên ngoài như agentic-qe-fleet, agentdb và agentic-flow: chỉ cài từ một marketplace duy nhất. Bật từ cả hai nơi thì mod và lệnh có thể nạp hai lần. Gỡ một bản đi.
E.Lo ngại về quyền hạn của mod
README nói thẳng: mod chạy với quyền của tài khoản bạn và không bị sandbox. Hãy đọc mã nguồn trước khi cài, và đừng nâng mức Claude control lên full hay auto nếu chưa hiểu rõ. Mặc định read + ask là mức an toàn nhất.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh, dùng giấy phép MIT, cộng đồng lớn và còn được cập nhật. Bạn có đủ cả agent, bộ nhớ, bảng điều khiển và các lớp kiểm soát quyền, rất hợp nếu đã dùng Claude Code hàng ngày và muốn giao việc lớn hơn. Cách tiếp cận «cứ dùng Claude Code như thường» giúp người mới đỡ ngợp.
Giới hạn. Công cụ rất rộng: hàng chục plugin, hàng trăm công cụ MCP. Người mới dễ ngợp nếu cố học hết. init thêm khá nhiều file vào dự án nên cần dùng Git để theo dõi thay đổi. Chạy nhiều agent có thể tốn token. Các bản demo trong README dùng dữ liệu mẫu hoặc phiên ghi sẵn, nên bạn cần tự đánh giá chất lượng kết quả trên dự án của mình. Mod không có sandbox, nên cần đọc mã trước khi cài.
Khi nên chọn cách khác. Nếu bạn chỉ cần Claude Code làm vài việc nhỏ lẻ, bản thân Claude Code là đủ. Nếu chỉ muốn thử một chức năng, hãy cài đúng một plugin thay vì cả bộ. Nếu không dùng terminal hay không có Node 20, bạn sẽ gặp khó ngay từ bước đầu. Lời khuyên của mình: thử trên một dự án nhỏ hoặc nhánh Git riêng, giữ quyền ở mức read + ask, rồi mở rộng 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 tự do. Tuy nhiên Ruflo chạy cùng Claude Code hoặc Codex, các dịch vụ này có điều khoản và chi phí riêng của chúng. Tư liệu tôi có không nêu bảng giá.
Ruflo khác gì Claude Code?
Claude Code là trợ lý lập trình; Ruflo là lớp điều phối bao quanh nó. Theo README, Ruflo thêm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook, bảng điều khiển và các lớp bảo mật, nên Claude Code làm việc có tổ chức hơn.
Cần Node phiên bản nào để cài?
package.json yêu cầu Node từ 20.0.0 trở lên. Lệnh cài chính là `npx ruflo@latest init`, chạy trong thư mục dự án. Nếu đi đường plugin thì cần Claude Code từ 2.1.287 trở lên.
Có 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: cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. README cũng có lệnh `npx ruflo init --grok` cho Grok Build.
Cài plugin và chạy npx init khác nhau thế nào?
Plugin không thêm file nào vào dự án nhưng chỉ cho lệnh slash, vài skill và định nghĩa agent, không có hook. `npx ruflo init` thêm các thư mục như .claude/ và .claude-flow/, kèm MCP server, hook và daemon, là cách README khuyên dùng cho việc thật.
Có an toàn khi cho Claude điều khiển bảng điều khiển không?
README nói mức mặc định là read + ask, và hành động liên quan mạng, chi tiêu hay phá huỷ luôn cần xác nhận kể cả khi để auto. Bạn có thể bấm Take back control để dừng. Riêng các mod thì chạy với quyền tài khoản của bạn và không có sandbox, nên cần đọc mã trước khi cài.
Ruflo có cần GPU hoặc chạy được trên Windows không?
Tư liệu tôi có chưa nêu yêu cầu GPU hay danh sách hệ điều hành được hỗ trợ. Điều kiện duy nhất README ghi rõ là Node 20 trở lên. Bạn nên xem thư mục docs/ trong repo để biết thêm.


