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 (tiền thân là Claude Flow) là một agent harness: lớp bao quanh Claude Code hoặc Codex để thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên và công cụ điều phối. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node từ 20 trở lên. Với người mới, phần cài không khó, nhưng hệ thống rất rộng nên nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một «agent harness» mã nguồn mở, tức lớp công cụ bao quanh Claude Code hoặc Codex để các AI agent làm việc có tổ chức hơn. Mô hình AI lo phần viết, còn Ruflo lo phần còn lại: giao việc, nhớ ngữ cảnh, phối hợp nhiều agent và kiểm soát quyền hạn. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.600 sao và khoảng 9.600 fork trên GitHub.
Bạn nên xem qua Ruflo nếu đã dùng Claude Code hoặc Codex và thấy một agent làm một mình thì chưa đủ. Lập trình viên mới, người làm kỹ thuật trong doanh nghiệp, hoặc ai muốn thử «đội AI» đều dùng được. Bạn không cần học hết các công cụ của nó. README nói thẳng: sau khi chạy init, bạn cứ dùng Claude Code như bình thường, hệ thống hook sẽ tự định tuyến tác vụ và phối hợp agent ở phía sau.
Điểm đáng giá nhất là cách cài rất gọn: một lệnh npx trong thư mục dự án là có agent, hook, bộ nhớ và MCP server. Nếu không muốn thêm file vào dự án, bạn có thể chọn đường cài bằng plugin của Claude Code, hoàn toàn không có file nào được thêm vào thư mục làm việc.
ruvnet/ruflo
Ruflo là bộ khung điều phối (harness) cho Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server vào dự án chỉ bằng một lệnh npx.
I.Ruflo làm được gì
Những điều dưới đây là các tính năng chính mà tư liệu của repo mô tả. Không phải cái nào bạn cũng cần dùng ngay.
- Nhiều agent chuyên biệt. Bản cài bằng CLI cho bạn 98 agent, hơn 60 lệnh và 30 skill. Lợi ích: thay vì một AI làm mọi thứ, bạn giao việc cho agent hợp từng loại (ví dụ rà soát code, viết test).
- Swarm (đội agent). Các agent tự tổ chức thành nhóm để chia việc cho nhau. Bạn chỉ cần mô tả mục tiêu, ví dụ «dùng một swarm để rà soát repo này».
- Bộ nhớ xuyên phiên. Agent nhớ lại kinh nghiệm giữa các lần làm việc. README mô tả phần tìm kiếm 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.
- Hook tự định tuyến. Sau
init, hook tự chọn cách xử lý tác vụ và học từ các mẫu làm thành công, bạn không phải gọi từng công cụ. - Liên kết (federation). Agent trên các máy khác nhau có thể trao đổi với nhau. README nói là giao tiếp an toàn, không làm lộ dữ liệu.
- Bảng điều khiển trong Claude Code. Plugin
ruflo-consolecho bạn theo dõi workflow, agent, model, token và chi phí ngay cạnh Claude Code. Bạn gõ/ruflođể mở. - Hệ plugin lớn. Có 48 plugin chính thức, 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 chỗ thiếu test và sinh test,ruflo-cost-trackertheo dõi token và đặt ngân sách,ruflo-security-auditquét lỗ hổng. - Chạy được với nhiều máy khách. Ngoài Claude Code, README nói Codex và các MCP client khác dùng được, kể cả Grok Build qua
npx ruflo init --grok.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu ít yêu cầu cụ thể, bạn cần:
- Node.js từ phiên bản 20.0.0 trở lên. Đây là yêu cầu trong
package.json. Ruflo chạy quanpxnên cần có Node và npm. - Claude Code nếu bạn dùng đường cài
inithoặc plugin. Riêng đường plugin cần Claude Code 2.1.287 trở lên. Lệnh cài từ terminal (claude plugin install ...) cần 2.1.292 trở lên. - Một thư mục dự án để chạy lệnh
initbên trong. - Nếu dùng Codex hay MCP client khác: client đó phải cho cấu hình MCP server bằng lệnh và tham số.
Về hệ điều hành, tài khoản AI, API key hay phần cứng (GPU, RAM), phần README mình có chưa nói rõ. Bạn xem thêm trong thư mục docs/ của repo và file README.md đầy đủ. Bản thân Claude Code và Codex có yêu cầu tài khoản riêng của chúng.
Mods của Ruflo chạy với đúng quyền tài khoản của bạn và không bị đặt trong sandbox. README khuyên đọc mã của mod trước khi cài. Hãy làm đúng như vậy.
III.Cài đặt từng bước
Ruflo có ba đường cài chính. Mình mô tả đường phổ biến nhất (CLI) trước, rồi đến plugin và MCP.
- Mở terminal đúng thư mụcVào thư mục dự án của bạn
- Chạy initMột lệnh npx thêm agent, hook, bộ nhớ, MCP server
- 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 thử một tác vụDùng câu lệnh mẫu để thử swarm
- Mở bảng điều khiểnGõ /ruflo (nếu đã cài ruflo-console)
A.Mở terminal trong thư mục dự án
Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. init ghi file vào thư mục hiện tại, nên bạn cần mở terminal đúng ở thư mục dự án. Ví dụ:
cd ten-thu-muc-du-anThay ten-thu-muc-du-an bằng đường dẫn thật của bạn. Nếu chưa có Node, hãy cài Node từ 20 trở lên trước.
B.Chạy lệnh init
Đây là lệnh chính trong 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. Lệnh init thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh của README, bạn sẽ thấy các file và thư mục như .claude/, .claude-flow/, CLAUDE.md xuất hiện trong dự án. Nếu dự án đã có CLAUDE.md riêng, bạn nên sao lưu trước khi chạy.
Muốn cấu hình từng bước theo kiểu hỏi đáp, README có lệnh:
npx ruflo@latest init wizardC.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 lúc chạy init, hãy thoát ra và mở lại.
D.Cách khác: chỉ cài plugin cho Claude Code
Đường này không thêm file nào vào dự án, và cài bộ công cụ cốt lõi, bảng điều khiển và các mod. Chạy các lệnh sau 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
/rufloDòng đầu thêm «chợ» plugin của Ruflo. Ba dòng install cài từng plugin. /reload-plugins nạp lại, và /ruflo mở bảng điều khiển. Nếu thích cài từ terminal (Claude Code 2.1.292 trở lên), README có lệnh:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloNgoài ra bạn có thể thêm ruflo-swarm, ruflo-rag-memory... bằng cùng kiểu lệnh /plugin install <tên>@ruflo. README lưu ý đây là bản «nhẹ»: chỉ có lệnh gạch chéo, một vài skill và định nghĩa agent. Hook và đầy đủ vòng lặp chỉ có ở đường CLI.
E.Cách khác: Codex hoặc MCP client khác
Không cần cài sẵn dự án. Bạn cấu hình trong client: command là npx, arguments là:
["-y", "ruflo@latest", "mcp", "start"]Cách khai báo MCP server nằm ở phần cài đặt riêng của từng client. README của Ruflo không hướng dẫn chi tiết từng client, bạn xem tài liệu của client bạn dùng.
F.Chạy thử giao diện terminal (không cần Claude Code)
Bảng điều khiển còn chạy độc lập:
npx ruflo tuiThêm --plain để in ra một khung duy nhất, hợp với script.
IV.Kiểm tra đã chạy được chưa
Có vài dấu hiệu bạn có thể kiểm tra theo đúng tư liệu:
- Sau
init: trong thư mục dự án xuất hiện.claude/,.claude-flow/vàCLAUDE.md. Đây là các file README liệt kê cho đường CLI. - Với đường plugin: gõ
/plugintrong Claude Code, các plugin vừa cài (nhưruflo-console,ruflo-mods) phải hiện trong dòng mod đang hoạt động. - Bảng điều khiển: gõ
/ruflovà thấy giao diện cockpit mở ra. - Chạy thật: thử tác vụ mẫu của README (ở phần dưới) và xem Claude Code có dùng swarm hay không.
Nếu init chạy xong mà Claude Code không có gì thay đổi, hãy chắc rằng bạn đã khởi động lại nó trong đúng thư mục.
V.Dùng vào việc thật
Dưới đây là các tình huống bám theo những gì README mô tả. Kết quả thực tế phụ thuộc vào dự án và mô hình bạn dùng.
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 vừa nhận một dự án cũ, ít test. Sau khi chạy init và mở lại Claude Code, bạn gõ đúng 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.Kết quả mong đợi: Claude Code dùng swarm để tìm module rủi ro nhất, viết test cho nó và tóm tắt việc đã làm. Bạn vẫn nên đọc lại test và diff trước khi giữ lại.
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.Theo dõi chi phí và tiến độ bằng bảng điều khiển
Bối cảnh: bạn chạy nhiều agent và muốn biết đang tốn bao nhiêu token. Cài ruflo-console, mở /ruflo. Bảng điều khiển cho bạn theo dõi workflow, agent, model, token và chi phí, đồng thời mở nhật ký agent để tìm việc bị lỗi. Plugin ruflo-cost-tracker bổ sung việc đặt ngân sách và cảnh báo chi phí.
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 Claude tạo một «mission» trong console nhưng không muốn nó làm tràn lan. Bạn làm theo README: vào Settings → Claude control, 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ở trang Missions, đặt mục tiêu và chờ bạn xác nhận thao tác tạo. Mức mặc định là read + ask. Bạn có thể bấm Take back control để dừng ngay. Lưu ý của README: tạo mission không có nghĩa tính năng đã được làm xong.
D.Dùng Ruflo qua Codex hoặc MCP client khác
Bối cảnh: nhóm bạn dùng Codex thay cho Claude Code. Bạn khai báo MCP server với command npx và tham số -y ruflo@latest mcp start, như phần cài đặt ở trên. Từ đó Codex gọi được các công cụ MCP của Ruflo. README nói công cụ MCP của Ruflo rất nhiều (406 công cụ), nhưng bạn không phải học hết.
VI.Lỗi hay gặp và cách xử lý
Các lỗi dưới đây là những tình huống rất dễ xảy ra với loại công cụ này, không phải danh sách chính thức của repo.
npxbáo lỗi hoặc phiên bản Node cũ. Ruflo yêu cầu Node từ 20 trở lên. Chạynode --versionđể kiểm tra, nâng Node lên rồi chạy lại.initchạy xong nhưng Claude Code không thấy gì mới. Thường do bạn chưa khởi động lại Claude Code hoặc mở nhầm thư mục. Thoát,cdđúng thư mục dự án và mở lại.- Lệnh
/plugin installkhông nhận hoặc báo thiếu. Đường plugin cần Claude Code 2.1.287 trở lên (2.1.292 trở lên cho lệnhclaude plugin install). Cập nhật Claude Code, sau đó chạy/reload-plugins. - Plugin bị nạp hai lần. 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, nếu không mod và lệnh sẽ nạp đôi. Hãy gỡ bản cài thừa. - Ghi đè file cấu hình có sẵn. Đường CLI thêm
CLAUDE.md,.claude/và các file khác. Nên dùng git hoặc sao lưu trước khi chạyinittrong dự án đang có cấu hình riêng. Với Grok, README có cờ--dry-runđể xem trước.
VII.Có nên dùng không
Điểm mạnh: cài bằng một lệnh, giấy phép MIT, repo vẫn được cập nhật trong 3 tháng gần đây, hỗ trợ cả Claude Code lẫn Codex và MCP client khác. Có hệ plugin rộng (48 plugin) và bảng điều khiển để nhìn thấy agent đang làm gì. Phần điều khiển có giới hạn rõ (read, write, manage, full; ask hoặc auto), và README nói các hành động mạng, chi tiêu, phá huỷ vẫn cần xác nhận ngay cả ở chế độ auto.
Giới hạn: hệ thống rất lớn, nên người mới dễ choáng. Bản plugin chỉ là bản nhẹ, không có hook. README cũng tự nói các video demo dùng dữ liệu mẫu, chưa chứng minh được việc swarm hoàn thành hay bộ nhớ gợi lại. Phần mô tả «tự học» được README gọi là mô hình khái niệm. Mod chạy không sandbox nên cần đọc mã trước khi cài. Chi phí gọi mô hình AI phụ thuộc tài khoản của bạn, và README mình có chưa nêu rõ.
Khi nào chọn cách khác: nếu bạn chỉ cần một trợ lý viết code đơn giản, Claude Code hoặc Codex trần là đủ. Nếu bạn cần mọi thứ chạy ổn định ngay mà không muốn thêm file vào dự án, hãy thử đường plugin trước. Còn nếu muốn đội agent phối hợp, có bộ nhớ và hook, đường npx ruflo@latest init mới đủ bộ. Hãy thử trên một dự án nhỏ, có git, trước khi áp dụng cho dự án 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 tự do. Tuy nhiên chi phí gọi mô hình AI (Claude, Codex...) tính theo tài khoản của bạn ở các dịch vụ đó. README mình có chưa nêu rõ bảng giá.
Ruflo cần Node phiên bản nào?
File package.json yêu cầu Node từ 20.0.0 trở lên. Bạn chạy Ruflo qua npx, ví dụ `npx ruflo@latest init`.
Ruflo khác gì dùng Claude Code trơn?
Ruflo là lớp harness bao quanh Claude Code và Codex. Nó thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook tự định tuyến và bảng điều khiển. Claude Code vẫn là nơi bạn làm việc, Ruflo bổ sung công cụ phía sau.
Có cần cài file vào dự án không?
Tuỳ đường cài. Lệnh `npx ruflo@latest init` thêm các thư mục và file như .claude/, .claude-flow/ và CLAUDE.md. Đường plugin cho Claude Code thì không thêm file nào vào dự án.
Ruflo dùng được với Codex không?
Có. README nói Codex và các MCP client khác dùng được: cấu hình command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`.
Có chạy được trên Windows không, có cần GPU không?
Tư liệu mình có chưa nói rõ về hệ điều hành hay yêu cầu GPU. Bạn xem thêm tài liệu trong thư mục docs/ của repo. Yêu cầu chắc chắn duy nhất là Node từ 20 trở lên.
Claude có thể tự làm mọi thứ trong bảng điều khiển không?
Không. Tính năng Claude control có các mức read, write, manage, full và hai chế độ ask hoặc auto, mặc định là read + ask. README nói hành động mạng, chi tiêu và phá huỷ vẫn cần xác nhận kể cả ở chế độ auto, và bạn có thể bấm Take back control để dừng.


