Ruflo: điều phối nhóm 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 là một "agent meta-harness": lớp công cụ đặt quanh Claude Code và Codex để thêm agent chuyên biệt, bộ nhớ qua nhiều phiên, hook tự động và máy chủ MCP. Bạn dùng nó để Claude Code làm việc theo nhóm thay vì từng agent riêng lẻ. Cài khá đơn giản: chạy một lệnh npx trong thư mục dự án, cần Node 20 trở lên.
Ruflo là một bộ khung (harness) đặt quanh Claude Code và Codex. README gọi nó là "agent meta-harness". Nói đơn giản: mô hình AI viết code, còn Ruflo cung cấp công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát để mô hình làm việc được như một nhóm.
Bạn nên xem repo này nếu đang dùng Claude Code hoặc Codex và muốn nhiều hơn một agent trả lời từng câu. Ruflo thêm hơn 100 agent chuyên biệt, các "swarm" (nhóm agent phối hợp), bộ nhớ tự học giữa các phiên, và cả liên kết agent giữa nhiều máy. Dự án hiện có khoảng 81.588 sao và 9.608 fork trên GitHub, giấy phép MIT, và vẫn được cập nhật trong ba tháng gần đây.
Điểm đáng giá nhất là cách vào cửa rất nhẹ: một lệnh npx ruflo@latest init trong thư mục dự án. Sau đó bạn cứ dùng Claude Code như bình thường, các hook sẽ tự định tuyến tác vụ và phối hợp agent ở phía sau. Bài này hướng dẫn cài, kiểm tra và dùng vào vài việc cụ thể, bám đúng những gì README nói.
ruvnet/ruflo
Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, hook và máy chủ MCP, chỉ cần một lệnh npx để cài.
I.Ruflo làm được gì
Ruflo không phải một ứng dụng riêng. Nó là lớp "hệ thần kinh" gắn vào công cụ bạn đang dùng. Các phần chính:
- Agent và swarm. Hơn 100 agent chuyên biệt tự tổ chức thành nhóm. Bạn giao một việc lớn, các agent chia nhau làm. README mô tả luồng khái quát: người dùng → Ruflo (CLI/MCP) → bộ định tuyến → swarm → agent → bộ nhớ → nhà cung cấp mô hình.
- Bộ nhớ qua nhiều phiên. Agent nhớ lại kinh nghiệm từ những lần làm trước và dùng để định tuyến tốt hơn. README lưu ý đây là mô hình khái niệm: 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.
- Hook tự động. Sau
init, bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Hook tự định tuyến tác vụ và học từ những mẫu thành công. - Máy chủ MCP. Codex và các ứng dụng khách MCP khác có thể trỏ vào Ruflo để dùng chung công cụ.
- Liên kết (federation). Agent trên các máy khác nhau nói chuyện với nhau một cách an toàn, theo README là không làm rò rỉ dữ liệu.
- Bảng điều khiển (console / cockpit). Một giao diện cạnh Claude Code để theo dõi workflow, agent, mô hình, token và chi phí; xem log, tìm kiếm, phát lại và so sánh các lần chạy.
- Chợ plugin. Có 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à tạo test,ruflo-cost-trackertheo dõi token và đặt ngân sách.
II.Cần chuẩn bị gì
Tư liệu nêu những điều sau:
- Node.js 20.0.0 trở lên (theo package.json). Lệnh
npxđi kèm Node. - Claude Code nếu bạn dùng cách cài trọn bộ hoặc cách plugin. Cách chỉ cài 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. - Nếu dùng Codex hay ứng dụng khách MCP khác, bạn chỉ cần cấu hình lệnh chạy máy chủ MCP (xem bước sau).
README phần đã cho không nói về yêu cầu GPU, hệ điều hành cụ thể hay API key riêng cho Ruflo. Phần này chưa có thông tin; bạn xem thêm trong thư mục docs/ của repo hoặc hướng dẫn người dùng mà README trỏ tới. Lưu ý Claude Code và các mô hình bạn dùng phía sau có thể cần tài khoản riêng của chúng.
III.Cài đặt từng bước
README có ba đường: cài trọn bộ bằng npx, cài chỉ plugin trong Claude Code, hoặc cấu hình cho Codex/MCP. Bạn chọn một. Với người mới, mình khuyên đường đầu tiên.
- Mở terminal đúng chỗVào 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
- 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Đưa cho Claude Code một tác vụ thật có nhắc đến swarm
- (Tuỳ chọn) Dùng cách khácCài plugin, nối Codex qua MCP, hoặc chạy giao diện terminal
A.Mở terminal trong thư mục dự án
Đây là chỗ người mới hay vấp. 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. Nếu chưa có dự án, hãy tạo một thư mục thử nghiệm riêng.
cd duong-dan-toi-du-an-cua-banThay duong-dan-toi-du-an-cua-ban bằng đường dẫn thật trên máy bạn.
B.Chạy lệnh init
Đây là lệnh chính trong README:
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. Theo bảng so sánh trong README, cách này tạo thêm .claude/, .claude-flow/, CLAUDE.md, các file hỗ trợ và file cài đặt trong dự án. Vì vậy nếu dự án đã có CLAUDE.md, bạn nên sao lưu hoặc dùng quản lý phiên bản (git) để xem lại thay đổi.
Nếu muốn thiết lập theo kiểu hỏi đáp, README ghi có lệnh:
npx ruflo@latest init wizardInit ghi file vào thư mục dự án. Hãy chạy thử trên dự án có git hoặc thư mục sao lưu để xem được chính xác những gì đã thay đổi.
C.Mở Claude Code và giao việc
Mở Claude Code trong cù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, nên nếu Claude Code đang mở sẵn, hãy thoát ra rồi mở lại. Sau đó thử câu lệnh 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.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. Nó cài công cụ lõi, bảng điều khiển và các "mod" chạy trong Claude Code. 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
/rufloVới Claude Code từ 2.1.292 trở lên, README ghi có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloREADME cảnh báo: các mod chạy với quyền của tài khoản bạn và không bị đưa vào sandbox, nên hãy đọc mã trước khi cài.
Bảng so sánh trong README cũng nói rõ: cách plugin là bản "lite", chỉ có lệnh gạch chéo, vài kỹ năng và định nghĩa agent, không có hook và chỉ đăng ký máy chủ MCP nếu có ruflo-core. Muốn trọn vòng lặp như tài liệu mô tả thì dùng npx ruflo@latest init.
E.Cách khác: nối Codex hoặc ứng dụng khách MCP
Không cần thiết lập dự án. Trong phần cấu hình MCP của ứng dụng, đặt command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]README cũng ghi dạng lệnh đầy đủ tương đương là npx -y ruflo@latest mcp start.
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 một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Theo README, có vài dấu hiệu để biết cài xong:
- Sau
npx ruflo@latest initvà khởi động lại Claude Code, gõ/ruflosẽ mở bảng điều khiển. - Trong thư mục dự án xuất hiện
.claude/,.claude-flow/vàCLAUDE.md. - Nếu cài bằng plugin, mở
/pluginvà kiểm tra các plugin xuất hiện trong dòng "active mods". - Với
npx ruflo tui, giao diện bảng điều khiển hiện ngay trong terminal.
README không nêu một dòng "kết quả mong đợi" cụ thể cho lệnh init. Nếu không thấy thay đổi gì, xem thư mục docs/ hoặc phần hướng dẫn người dùng của repo.
V.Dùng vào việc thật
A.Rà soát một repo và viết test cho chỗ rủi ro nhất
Bối cảnh: bạn là lập trình viên mới, vừa nhận một dự án cũ và chưa biết đụng vào đâu. Sau khi chạy init và mở lại Claude Code, bạn đưa đúng câu lệnh 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: một nhóm agent cùng tìm module rủi ro nhất, viết test cho nó, rồi tóm tắt những gì đã đổi. Bạn đọc bản tóm tắt và xem lại thay đổi trong git trước khi giữ lại.
Agent = Model + Harness. Mô hình viết, còn bộ khung lo công cụ, bộ nhớ và kiểm soát để nó làm việc được thật.
Ông T
B.Theo dõi công việc trong bảng điều khiển
Bối cảnh: bạn muốn thấy agent đang làm gì, tốn bao nhiêu token và chi phí. Sau khi cài, mở Claude Code và gõ:
/rufloBảng điều khiển hiển thị workflow, agent, mô hình, token và chi phí cạnh Claude Code. Bạn có thể mở log, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Hợp với người quản lý nhóm nhỏ muốn biết agent làm gì mà không phải đọc từng dòng log thô.
C.Để Claude điều khiển bảng điều khiển, nhưng bạn đặt giới hạn
Bối cảnh: bạn muốn thử giao việc quản lý cho Claude. README mô tả cách làm an toàn từng bước: vào Settings → Claude control, 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 tại là read + ask. Chọn write + ask, rồi nhờ:
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 thao tác tạo. Kiểm tra bằng cách xem Missions có mục tiêu mới và Overview có ghi lại hành động. README nhấn mạnh: tạo một mission không có nghĩa là tính năng đã được làm. Muốn dừng, bấm Take back control.
D.Dùng Ruflo từ Codex hoặc công cụ MCP khác
Bối cảnh: bạn không dùng Claude Code mà dùng Codex. Cấu hình MCP với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"] như phần trên. Công cụ của Ruflo sẽ xuất hiện trong ứng dụng khách MCP đó mà không phải thiết lập thêm trong dự án. README không liệt kê chi tiết từng công cụ ở phần đã cho, nên hãy xem danh sách công cụ trong chính ứng dụng của bạn sau khi nối.
VI.Lỗi hay gặp và cách xử lý
README phần đã cho không có mục xử lý sự cố. Dưới đây là các lỗi rất dễ gặp với loại công cụ này, kèm cách xử lý an toàn.
Lệnh npx báo lỗi hoặc không chạy. Kiểm tra phiên bản Node bằng node --version. package.json yêu cầu Node 20.0.0 trở lên; nếu thấp hơn, hãy nâng cấp Node rồi chạy lại.
Claude Code không thấy agent hay công cụ mới. README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy thoát hẳn rồi mở lại trong đúng thư mục đã chạy init. Với cách plugin, gõ /reload-plugins rồi kiểm tra /plugin.
Lệnh /plugin install không được. Cách 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 cập nhật Claude Code trước.
Cài agentdb hoặc plugin ngoài từ hai chợ cùng lúc. 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 chợ, nếu bật cả hai thì mod và lệnh bị nạp hai lần. Hãy gỡ một bên.
Claude làm quá phạm vi bạn muốn. Giữ mặc định read + ask trong Claude control và chỉ nâng quyền khi cần. README nói các hành động mạng, chi tiền và phá huỷ vẫn cần xác nhận ngay cả ở chế độ auto. Có thể bấm Take back control bất cứ lúc nào.
VII.Có nên dùng không
Điểm mạnh.
- Cài nhanh, một lệnh, giấy phép MIT.
- Hỗ trợ nhiều đường vào: Claude Code, Codex, ứng dụng khách MCP khác, và cả giao diện terminal riêng.
- Có sẵn bảng điều khiển để theo dõi agent, token và chi phí.
- Có cơ chế giới hạn quyền cho Claude khi điều khiển bảng điều khiển.
Giới hạn.
- Hệ sinh thái rất lớn (hàng chục plugin, hàng trăm công cụ MCP). Người mới dễ choáng; hãy bắt đầu bằng
initvà một tác vụ thật. - Cách
initghi nhiều file vào dự án. Bạn cần quản lý phiên bản để kiểm soát thay đổi. - README tự nói nhiều đoạn minh hoạ chỉ là mô hình khái niệm hoặc dữ liệu mẫu, không phải bằng chứng một swarm đã hoàn tất công việc hay bộ nhớ đã được gọi lại. Hãy tự kiểm chứng kết quả trên dự án của bạn.
- Các mod chạy với quyền tài khoản và không có sandbox, nên cần đọc mã trước khi cài.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời từng câu hỏi lẻ trong một file nhỏ, bản Claude Code thuần là đủ và nhẹ hơn. Ruflo đáng thử khi bạn có việc nhiều bước, muốn nhiều agent phối hợp, muốn bộ nhớ qua nhiều phiên và cần theo dõi chi phí. Nếu chỉ muốn thử vài lệnh mà không thêm file vào dự án, hãy chọn cách cài plugin.
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 dùng và sửa được tự do. Tư liệu không nói gì về chi phí của các mô hình hay dịch vụ phía sau như Claude Code hay Codex, nên bạn cần tự kiểm tra gói tài khoản của chúng. Ruflo có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.
Ruflo chạy trên Windows được không?
Tư liệu phần đã cho chưa nêu rõ hệ điều hành được hỗ trợ. Yêu cầu duy nhất được ghi là Node.js 20.0.0 trở lên. Bạn nên thử trên dự án nhỏ hoặc xem thêm trong thư mục docs của repo.
Cần GPU không?
Phần README đã cho không nhắc yêu cầu GPU cho cách cài cơ bản. Chỉ có mô tả plugin ruflo-ruvector là tìm kiếm tăng tốc bằng GPU, và đó là plugin tuỳ chọn. Với dùng cơ bản bằng npx ruflo@latest init, chưa có thông tin cần GPU.
Ruflo khác gì Claude Code thuần?
Claude Code là công cụ để mô hình viết và sửa code. Ruflo là lớp harness bao quanh nó, thêm hơn 100 agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook tự động và máy chủ MCP. Bạn vẫn dùng Claude Code như bình thường, Ruflo phối hợp ở phía sau.
Dữ liệu của tôi có an toàn không?
README nói có các lớp kiểm soát bảo mật cho doanh nghiệp và federation giữa các máy mà không làm lộ dữ liệu. Bảng điều khiển có mức quyền read/write/manage/full và hành động nhạy cảm vẫn cần xác nhận. Tuy vậy các mod 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.
Dùng với Codex hoặc công cụ khác ngoài Claude Code được không?
Được. README ghi Codex và ứng dụng khách MCP khác dùng được: cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Có thêm tuỳ chọn init --grok cho Grok Build, và lệnh npx ruflo tui để chạy giao diện terminal riêng.
Nên chọn cài bằng npx init hay bằng plugin?
Theo README, npx ruflo@latest init cho trọn vòng lặp (agent, lệnh, kỹ năng, máy chủ MCP, hook, daemon) nhưng ghi file vào dự án. Cách plugin không thêm file nào vào dự án nhưng chỉ có lệnh gạch chéo, vài kỹ năng và định nghĩa agent, không có hook. README gợi ý cách init cho việc dùng thật, plugin để thử từng phần.


