Ruflo: điều phối nhiều agent AI 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 là một agent harness mã nguồn mở (giấy phép MIT, viết bằng TypeScript), bọc quanh Claude Code và Codex để thêm agent chuyên biệt, hook, bộ nhớ và MCP server. Bạn chạy một lệnh `npx ruflo@latest init` trong thư mục dự án rồi dùng Claude Code như bình thường. Cài đặt khá đơn giản nếu đã có Node 20 trở lên, nhưng bộ công cụ rất lớn nên nên bắt đầu từ việc nhỏ.
Ruflo là một “agent harness” mã nguồn mở: lớp công cụ bao quanh Claude Code và Codex, giúp các AI agent có thêm bộ nhớ, hook, MCP server và khả năng phối hợp thành nhóm (swarm). Tác giả mô tả ngắn gọn: mô hình AI là bộ não viết code, còn harness là cái bàn làm việc đầy đủ dụng cụ để bộ não đó làm việc thật. Ruflo chính là cái bàn làm việc đó.
Bạn nên xem repo này nếu đã dùng Claude Code hoặc Codex và thấy một agent đơn lẻ chưa đủ: quên ngữ cảnh giữa các phiên, không biết chia việc, khó theo dõi chi phí. Ruflo thêm hơn 100 agent chuyên biệt, bộ nhớ lưu qua nhiều phiên và một giao diện “buồng lái” để xem agent đang làm gì.
Điểm đáng giá nhất là cách cài rất ngắn. README nói bạn không cần học hết hàng trăm công cụ MCP hay lệnh CLI. Sau khi init, bạn cứ dùng Claude Code như thường, phần hook sẽ tự định tuyến tác vụ và phối hợp agent ở phía sau. Repo hiện có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.
ruvnet/ruflo
Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ dài hạn, swarm phối hợp và MCP server chỉ với một lệnh init.
I.Ruflo làm được gì
Dưới đây là những nhóm tính năng chính, giải thích theo lợi ích thực tế.
A.Thêm agent và swarm cho Claude Code
Sau init, dự án của bạn có thêm các agent chuyên biệt, lệnh và skill. README ghi con số khoảng 98 agent, hơn 60 lệnh và 30 skill cho đường cài bằng CLI. Lợi ích: bạn có thể nhờ Claude Code xử lý một việc lớn bằng cách chia cho nhiều agent, thay vì một agent làm tất cả.
B.Bộ nhớ qua nhiều phiên
Ruflo có bộ nhớ tự học, lưu kinh nghiệm từ các tác vụ đã làm và dùng lại cho lần sau. Các plugin như ruflo-agentdb (cơ sở dữ liệu vector cho bộ nhớ agent), ruflo-rag-memory (tìm kiếm thông minh) và ruflo-rvf (lưu và khôi phục bộ nhớ giữa các phiên) phục vụ phần này. Lợi ích: bớt phải giải thích lại dự án mỗi lần mở phiên mới.
C.Buồng lái (console) ngay cạnh Claude Code
Plugin ruflo-console cho bạn theo dõi quy trình, agent, mô hình, token và chi phí. Bạn có thể mở log của agent, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Lệnh mở giao diện là /ruflo trong Claude Code.
D.Cho Claude điều khiển console, nhưng bạn đặt giới hạn
Trong Settings có mục “Claude control”. Bạn chọn mức quyền read, write, manage hoặc full, và chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask. README nói các hành động liên quan mạng, chi tiêu và phá hủy vẫn cần xác nhận ngay cả khi ở auto, và có nút “Take back control” để thu hồi quyền.
E.Hệ sinh thái plugin
README liệt kê 48 plugin (cộng thêm 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, mở rộng. Ví dụ: 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 và đặt ngân sách, ruflo-docs tạo và duy trì tài liệu.
F.Dùng được với Codex và client MCP khác
Ngoài Claude Code, README nói Codex và các client MCP khác dùng được bằng cách trỏ tới npx -y ruflo@latest mcp start. Ngoài ra có tùy chọn npx ruflo init --grok cho Grok Build.
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 như vậy. Lệnhnpxđi kèm Node. - Claude Code nếu bạn đi theo đường chính. Với đường chỉ cài plugin, README ghi cần Claude Code 2.1.287 trở lên. Lệnh
claude plugin installtừ terminal cần bản 2.1.292 trở lên. - Một thư mục dự án để chạy
init. Lệnh này ghi file vào thư mục đó.
README không nêu yêu cầu về hệ điều hành hay phần cứng cụ thể (như GPU), và không nói rõ cần API key nào để chạy cơ bản. Một số tính năng như học máy hay embeddings cần module cấu hình riêng; chi tiết xem thêm trong thư mục docs/ của repo.
Mod và plugin của Ruflo chạy với quyền tài khoản của bạn và không nằm trong sandbox. README khuyên đọc code của chúng trước khi cài. Hãy thử trong một dự án nháp trước khi đụng vào dự án thật.
III.Cài đặt từng bước
README có ba đường cài. Mình hướng dẫn đường chính (CLI init) trước, rồi hai đường phụ.
- Mở terminal đúng thư mụcVào thư mục dự án mà bạn muốn thêm Ruflo
- Chạy initDùng npx để thêm agent, hook, bộ nhớ và MCP server vào dự án
- Khởi động lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thậtGõ yêu cầu dùng swarm của Ruflo
- Mở buồng láiGõ /ruflo trong Claude Code để xem console
A.Mở terminal ở 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. Nếu chưa có dự án, hãy tạo một thư mục nháp để thử. Ví dụ trên Windows, bạn mở PowerShell rồi dùng cd để vào thư mục:
cd đường-dẫn-tới-thư-mục-dự-án-của-bạnB.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initnpx tải và chạy gói ruflo bản mới nhất mà không cần cài toàn cục. init thêm agent, hook, bộ nhớ và MCP server vào dự án. README cho biết đường này tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings trong dự án của bạn. Nếu bạn đã có CLAUDE.md riêng, hãy sao lưu trước.
Nếu muốn thiết lập theo kiểu hỏi đáp, README có lệnh:
npx ruflo@latest init wizardNếu muốn xem trước, README có nói về cờ --dry-run cho phiên bản --grok:
npx ruflo init --grokLệnh trên dành riêng cho Grok Build, ghi bề mặt dự án (.grok/, team bus và hướng dẫn vận hành) và không ghi gì ngoài dự án. Bạn thêm --dry-run để xem trước.
C.Khởi động lại Claude Code
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 tiếp theo. Nếu bạn đang mở sẵn Claude Code, hãy thoát và mở lại.
D.Đường phụ 1: chỉ cài plugin Claude Code (không thêm file vào dự án)
Đường này cài công cụ lõi, buồng lái và mod, không thêm file nào vào dự án. Chạy 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
/rufloTừng dòng làm gì: dòng đầu thêm “chợ” plugin của Ruflo; ba dòng install cài từng plugin; /reload-plugins nạp lại; /ruflo mở buồng lái. Từ terminal thường, trên Claude Code 2.1.292 trở lên, bạn có thể dùng:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloREADME cũng ghi ruflo-swarm (hiện swarm trong một pane) và ruflo-ruos (thêm đoạn trạng thái ruOS) là các plugin tùy chọn.
E.Đường phụ 2: Codex hoặc client MCP khác
Bạn cấu hình command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Cách điền vào client cụ thể (Codex, v.v.) tùy giao diện của từng client; README chưa kèm ví dụ file cấu hình, nên bạn xem thêm tài liệu của client đó.
F.Đường phụ 3: chạy console trong terminal thường
Console chạy độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain để in một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Với đường init, README mô tả các dấu hiệu sau:
- Trong thư mục dự án xuất hiện các mục như
.claude/,.claude-flow/vàCLAUDE.md. - Sau khi khởi động lại Claude Code, gõ
/ruflosẽ mở buồng lái. - Giao một tác vụ thật cho Claude Code (xem phần dưới) và xem agent được điều phối.
Với đường chỉ cài plugin, README nói bạn mở /plugin và kiểm tra các mod xuất hiện trong dòng “active mods”. Trong console, lệnh /ruflo market mở danh mục plugin, nơi bạn cài, bật, tắt và cập nhật (mỗi hành động đều hỏi lại bạn trước).
Với đường Codex/MCP, README chưa nêu cách kiểm tra riêng. Bạn có thể xem client của mình có liệt kê được các công cụ MCP của ruflo hay không.
V.Dùng vào việc thật
Các tình huống dưới đây bám đúng khả năng được README mô tả. Kết quả thực tế sẽ tùy dự án và mô hình bạn dùng.
A.Dev mới nhận một dự án lạ: nhờ swarm rà soát
Bạn vừa nhận một repo chưa quen. Sau khi init và mở lại Claude Code, bạn dán đúng câu README gợi ý:
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 yêu cầu swarm tìm module rủi ro nhất, viết test cho nó rồi tóm tắt thay đổi. Bạn nhận lại một bản tóm tắt và các file test mới để tự xem lại. Hãy đọc diff trước khi giữ lại.
Agent = Mô hình + Harness: mô hình viết code, còn harness cho nó công cụ, bộ nhớ và giới hạn để làm việc thật.
Ông T
B.Chủ dự án muốn nhìn rõ agent đang làm gì và tốn bao nhiêu
Bạn chạy một loạt tác vụ và muốn biết agent nào làm gì. Cài ruflo-console, mở /ruflo để theo dõi quy trình, token và chi phí; mở log để tìm tác vụ lỗi và phát lại. Nếu muốn có cảnh báo chi tiêu, README có plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Kết quả: bạn thấy bức tranh toàn cảnh thay vì đoán mò.
C.Thử cho Claude điều khiển console với quyền hạn chế
Đây là bài tập an toàn mà README mô tả từng bước:
- Mở
/ruflo, vào Settings → Claude control, chọn write + ask. - Gõ 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 đó và mục Overview có ghi lại hành động.
Lưu ý README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Nếu muốn dừng, bấm “Take back control”.
D.Dùng Ruflo như MCP server cho Codex
Nếu bạn dùng Codex hơn Claude Code, cấu hình MCP với command npx và arguments như ở phần cài đặt. Khi đó công cụ của Ruflo có sẵn trong client MCP của bạn mà không cần thêm file vào dự án. Kết quả cụ thể phụ thuộc vào client; README chưa có ví dụ chi tiết cho Codex.
VI.Lỗi hay gặp và cách xử lý
Một số lỗi dưới đây là suy ra từ cách hoạt động của loại công cụ này; chưa phải mọi lỗi đều có trong README.
A.Gõ /ruflo mà không thấy gì
Thường do Claude Code chưa nạp cấu hình. Hãy thoát và mở lại Claude Code trong đúng thư mục đã chạy init. Với đường plugin, chạy /reload-plugins, rồi mở /plugin xem plugin đã nằm trong danh sách chưa.
B.Lệnh /plugin install báo lỗi hoặc không có lệnh
README ghi đường plugin cần Claude Code từ 2.1.287 trở lên, và lệnh claude plugin install ở terminal cần từ 2.1.292. Hãy kiểm tra phiên bản Claude Code và cập nhật nếu đang dùng bản cũ.
C.npx không chạy được hoặc báo thiếu phiên bản
package.json yêu cầu Node 20.0.0 trở lên. Hãy kiểm tra bằng node --version; nếu thấp hơn, cài bản Node mới hơn rồi chạy lại lệnh.
D.Cài một plugin hai lần từ hai nơi
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 marketplace, vì nếu bật từ cả hai nơi, mod và lệnh sẽ nạp hai lần. Nếu thấy lệnh bị trùng, hãy gỡ một bản.
E.Hai kiểu cài trộn lẫn gây nhầm tên công cụ
README giải thích tên công cụ MCP khác nhau giữa đường plugin (dạng mcp__plugin_ruflo-core_ruflo__memory_store) và đường CLI (tên trần như memory_store). Nếu bạn làm theo tài liệu của đường này mà đang dùng đường kia, công cụ sẽ “không tìm thấy”. Hãy chọn một đường và bám theo nó.
VII.Có nên dùng không
Điểm mạnh. Cài đặt ngắn gọn chỉ với một lệnh; có sẵn nhiều agent, skill và plugin; có buồng lái để theo dõi; có cơ chế giới hạn quyền khi cho Claude điều khiển console; giấy phép MIT; dự án đang được cập nhật và có cộng đồng lớn.
Giới hạn. Bộ công cụ rất lớn nên người mới dễ choáng; đường init thêm khá nhiều file vào dự án; mod chạy với quyền tài khoản và không có sandbox. README cũng thẳng thắn rằng các video minh họa 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 hay bộ nhớ nhớ lại được. Phần học và truy xuất cục bộ vẫn cần embeddings và các module cấu hình đi kèm.
Khi nào nên chọn cách khác. Nếu bạn chỉ cần Claude Code làm các việc nhỏ lẻ, một mình nó là đủ, chưa cần thêm lớp điều phối. Nếu bạn chưa quen terminal, hãy thử đường plugin trước để không thêm file vào dự án. Nếu bạn làm việc với dữ liệu nhạy cảm, hãy đọc kỹ SECURITY.md và code của plugin trước khi cho chạy.
Lời khuyên của mình: thử trong một thư mục nháp, giao một việc nhỏ như ví dụ rà soát repo, xem kết quả rồi mới quyết định đưa vào dự án thật.
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 miễn phí. Tuy nhiên, các mô hình AI phía sau (như Claude hay Codex) có thể tính phí theo tài khoản của bạn. README có plugin `ruflo-cost-tracker` để theo dõi token và đặt ngân sách.
Ruflo có cần GPU không?
Tư liệu không nói Ruflo bắt buộc phải có GPU. Một plugin phụ là `ruflo-ruvector` được mô tả là có tìm kiếm tăng tốc GPU, nhưng đó là tùy chọn. Yêu cầu phần cứng chi tiết chưa có thông tin.
Ruflo chạy được trên Windows không?
README không nêu rõ hệ điều hành được hỗ trợ. Yêu cầu được ghi là Node 20.0.0 trở lên và lệnh `npx`. Bạn nên thử trong thư mục nháp trước, và xem thư mục `docs/` của repo nếu gặp vấn đề riêng của Windows.
Ruflo khác gì so với dùng Claude Code trực tiếp?
Claude Code là công cụ chính để viết code; Ruflo là lớp bao quanh nó. Ruflo thêm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook và buồng lái để theo dõi. Sau `init`, bạn vẫn dùng Claude Code như bình thường.
Dữ liệu của tôi có an toàn không?
README nói mod và plugin chạy với quyền tài khoản của bạn và không nằm trong sandbox, nên cần đọc code trước khi cài. Với tính năng Claude control, mặc định là read + ask, và các hành động liên quan mạng, chi tiêu, phá hủy luôn cần xác nhận. Repo có file SECURITY.md để bạn đọc thêm.
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 bằng cách cấu hình command là `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Ngoài ra có tùy chọn `npx ruflo init --grok` cho Grok Build.
Cài Ruflo có làm thay đổi dự án của tôi không?
Đường `npx ruflo@latest init` thêm file vào dự án, như `.claude/`, `.claude-flow/` và `CLAUDE.md`. Đường chỉ cài plugin Claude Code thì README ghi là không thêm file nào vào dự án. Bạn nên chọn đường phù hợp mức độ bạn muốn thay đổi.


