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à một agent meta-harness cho Claude Code và Codex, thêm vào dự án các agent chuyên biệt, bộ nhớ, hook và MCP server để nhiều agent phối hợp theo bầy (swarm). Bạn dùng nó để giao việc lớn cho Claude Code mà vẫn có kiểm soát. Cài đặt khá dễ: chỉ cần Node 20 trở lên và chạy một lệnh npx trong thư mục dự án.
Ruflo là một "agent meta-harness" cho Claude Code và Codex: một lớp công cụ bao quanh mô hình AI, giúp nó có thêm agent chuyên biệt, bộ nhớ, vòng lặp và các chốt kiểm soát để làm việc thật sự, thay vì chỉ trả lời từng câu. Repo trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, viết chủ yếu bằng TypeScript, giấy phép MIT. Hiện có khoảng 81588 sao và 9608 fork trên GitHub.
Tác giả giải thích bằng một công thức ngắn: Agent = Model + Harness. Mô hình lo phần viết. Harness lo phần còn lại: đưa công cụ, nhớ ngữ cảnh giữa các bước, chạy vòng lặp, đặt giới hạn. Ruflo là phần harness đó. Sau khi cài, bạn vẫn dùng Claude Code như bình thường, còn việc chọn agent, chia việc và ghi nhớ kinh nghiệm được hệ thống làm ngầm.
Repo hợp với lập trình viên đã dùng Claude Code và muốn giao những việc nhiều bước (rà soát code, viết test, tóm tắt thay đổi). Người làm văn phòng, kinh doanh cũng thử được nếu có người cạnh bên cài giúp lần đầu. Điểm đáng giá nhất là cài chỉ bằng một lệnh, có bảng điều khiển (console) để xem agent đang làm gì, và bạn tự đặt mức quyền cho Claude.
ruvnet/ruflo
Ruflo là lớp "harness" bao quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server để nhiều agent phối hợp làm việc, cài bằng một lệnh.
I.Ruflo làm được gì
Tư liệu của repo khá dài và có nhiều thứ. Bạn không cần học hết. README nói thẳng: bạn không phải học 406 công cụ MCP hay 61 lệnh CLI; sau init, cứ dùng Claude Code như bình thường. Dưới đây là những phần đáng biết nhất.
- Swarm (bầy agent). Nhiều agent tự tổ chức, chia nhau việc thay vì một agent làm tất cả. Với việc lớn như rà soát cả repo, cách này giúp mỗi agent tập trung một mảng.
- Kho agent dựng sẵn. Cài theo đường CLI, bạn nhận 98 agent, hơn 60 lệnh và 30 skill (số liệu trong bảng so sánh của README). Bạn không phải tự viết từng agent.
- Bộ nhớ qua nhiều phiên. Agent nhớ được kinh nghiệm giữa các lần làm việc. README mô tả phần này là vòng học 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, hook sẽ định tuyến tác vụ và học từ những mẫu làm việc thành công, chạy nền, bạn không phải gọi tay. - Console (buồng lái) trong Claude Code. Theo dõi workflow, agent, model, token và chi phí ngay cạnh Claude Code. Bạn xem được nhật ký và kết quả từng 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.
- Cho Claude điều khiển console nhưng bạn đặt giới hạn. Bật Settings → Claude control rồi chọn mức
read,write,managehoặcfull, cùng chế độ phê duyệtaskhoặcauto. Mặc định hiện là read + ask. Các thao tác mạng, tốn tiền hoặc phá huỷ vẫn phải xác nhận kể cả ở chế độauto. - 48 plugin cài riêng. Gồm nhóm điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), kiểm thử (testgen, browser), bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker) và nhiều nhóm khác. Bạn chỉ cài cái cần.
- Dùng được với Codex và MCP client khác. Chỉ cần trỏ client tới máy chủ MCP của Ruflo.
- Federation. Agent trên các máy khác nhau liên lạc với nhau. Đây là phần nâng cao, người mới có thể bỏ qua.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js từ 20.0.0 trở lên, vì
package.jsonyêu cầu>=20.0.0. Lệnhnpxđi kèm Node. - Claude Code nếu bạn đi theo đường chính. Riêng đường 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. - Một thư mục dự án để chạy
init. Lệnh này thêm file vào chính thư mục đó. - Nếu dùng Codex hoặc MCP client khác: client đó phải cho cấu hình một lệnh ngoài (command và arguments).
Tư liệu không nêu hệ điều hành bắt buộc, không nêu yêu cầu GPU, và không nói rõ có cần khoá API riêng hay không (bạn vẫn cần tài khoản dùng được Claude Code hoặc Codex). Các mục này chưa có thông tin rõ trong phần README mình đọc được.
Mod của Ruflo chạy với quyền tài khoản của bạn và không bị đóng khung (sandbox). README khuyên đọc code trước khi cài. Hãy giữ mức quyền Claude control ở read + ask lúc mới thử.
III.Cài đặt từng bước
README có ba đường: cài đầy đủ bằng npx, chỉ cài plugin trong Claude Code, hoặc nối qua MCP cho Codex. Người mới nên chọn đường đầu.
- Mở terminal trong thư mục dự ánVào đúng thư mục bạn muốn Ruflo làm việc
- Chạy initMột lệnh npx thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude CodeMở Claude Code trong cùng thư mục để nó nạp cấu hình mới
- Giao thử một việc thậtGõ câu lệnh mẫu để Claude dùng swarm
- (Tuỳ chọn) Cài plugin consoleDùng /plugin trong Claude Code để có buồng lái /ruflo
A.Mở terminal đúng thư mục dự án
Lệnh init ghi file vào thư mục hiện tại, nên bước này rất quan trọng. Trên Windows, bạn có thể mở PowerShell rồi đi tới thư mục dự án. Nếu dự án nằm trên GitHub và bạn chưa tải về, hãy clone trước (thay <chủ>/<repo> bằng dự án của bạn):
git clone https://github.com/<chủ>/<repo>.git
cd <repo>Người mới hay vấp ở chỗ chạy lệnh ngoài thư mục dự án, khiến file Ruflo nằm sai chỗ.
B.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initnpx tải và chạy Ruflo mà không cần cài toàn cục. init thêm vào dự án các agent, hook, bộ nhớ và MCP server. Theo bảng so sánh của README, thư mục của bạn sẽ có thêm .claude/, .claude-flow/, CLAUDE.md, các file hỗ trợ và file cài đặt. Nếu muốn cấu hình tương tác từng bước, README ghi:
npx ruflo@latest init wizardC.Mở lại Claude Code và giao việc thử
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nạp cấu hình ở lần khởi động kế tiếp, nên nếu nó đang mở sẵn, hãy đóng và mở lại. Rồi 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.Bạn có thể viết bằng tiếng Việt, nhưng câu mẫu trên là nguyên văn README nên chắc chắn đúng ý.
D.Cài console qua plugin (tuỳ chọn)
Đường này cho bạn buồng lái trong Claude Code mà không thêm file nào vào dự án. Gõ từng dòng trong chính 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 muốn cài từ terminal (Claude Code 2.1.292 trở lên):
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý README nói rõ đây là hai đường khác nhau. Plugin cho bạn lệnh gạch chéo và vài skill, không có hook. Đường npx ruflo@latest init mới cho trọn bộ vòng lặp (agent, hook, daemon, MCP server).
E.Dùng với Codex hoặc MCP client khác
Không cần cài vào dự án. Cấu hình client với command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. README cũng viết gọn là trỏ client tới lệnh npx -y ruflo@latest mcp start.
F.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 ra một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một dòng "cài thành công" cố định, nên mình chỉ nêu những dấu hiệu có trong tư liệu:
- Thư mục dự án có file mới. Sau
npx ruflo@latest init, bạn thấy.claude/,.claude-flow/vàCLAUDE.md. - Console mở được. Trong Claude Code, gõ
/ruflo. Nếu bạn cài plugin, mở/pluginvà kiểm tra các mod xuất hiện ở dòng "active mods". - Terminal UI lên hình. Chạy
npx ruflo tuivà thấy giao diện console. - Thử nhiệm vụ nhỏ. README gợi ý: đặt Claude control ở write + ask, rồi nhờ "Create a mission to add a dark mode toggle. Show me the mission and its status." Bạn xác nhận hành động tạo, rồi kiểm tra mục Missions có mục tiêu đó và Overview ghi lại hành động. Lưu ý: tạo mission không có nghĩa tính năng đã được viết.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo khả năng có trong README. Kết quả cụ thể phụ thuộc dự án và mô hình của bạn.
A.Rà soát một repo cũ 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 nhận một dự án không có test. Bạn chạy npx ruflo@latest init trong thư mục dự án, mở lại Claude Code và 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: các agent chia nhau xem code, chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn đọc lại tóm tắt và chạy test để kiểm chứng.
Giao cho AI việc lớn thì được, nhưng hãy đặt giới hạn trước và đọc kết quả sau.
Ông T
B.Theo dõi chi phí và agent bằng console
Bối cảnh: bạn lo AI chạy lâu sẽ tốn token mà không biết nó đang làm gì. Cài ruflo-console rồi gõ /ruflo. Console cho bạn xem workflow, agent, model, token và chi phí ngay cạnh Claude Code, đồng thời mở nhật ký từng agent để tra lỗi. Nếu muốn đặt ngân sách và cảnh báo, README có plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí).
C.Để Claude tự thao tác console trong giới hạn
Bối cảnh: bạn muốn Claude tự tạo và quản lý đầu việc, nhưng không muốn nó tự ý làm gì tốn tiền. Vào Settings → Claude control, chọn write và ask. Rồi nhờ:
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 bấm xác nhận hành động tạo. Kiểm tra Missions và Overview. Nếu thấy nó làm gì không ưng ý, bấm Take back control để dừng ngay các công cụ console của Claude; lệnh gọi sau đó sẽ bị từ chối cho đến khi bạn trả quyền lại.
D.Nối Ruflo vào Codex hoặc công cụ MCP khác
Bối cảnh: nhóm bạn dùng Codex chứ không chỉ Claude Code. Trong phần cấu hình MCP của client, đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Client sẽ khởi động máy chủ MCP của Ruflo và dùng các công cụ của nó. Muốn thiết lập theo dự án có hướng dẫn từng bước, chạy npx ruflo@latest init wizard.
VI.Lỗi hay gặp và cách xử lý
Tư liệu README không có mục xử lý sự cố, nên các mục dưới đây là những lỗi rất dễ xảy ra với loại công cụ này, kèm hướng xử lý an toàn.
A.Claude Code không thấy agent, hook hay lệnh /ruflo
Nguyên nhân hay gặp: Claude Code đang mở từ trước. README nói nó nạp cấu hình ở lần khởi động kế tiếp. Hãy đóng và mở lại trong đúng thư mục đã chạy init. Nếu cài plugin, chạy /reload-plugins. Mở /plugin để kiểm tra plugin đã bật.
B.Báo lỗi vì phiên bản Node quá cũ
package.json yêu cầu Node 20 trở lên. Kiểm tra bằng node --version. Nếu thấp hơn, nâng cấp Node rồi chạy lại lệnh npx.
C.Lệnh /plugin install không chạy hoặc không nhận
Đường plugin cần Claude Code 2.1.287 trở lên, và lệnh claude plugin install từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code trước. Cũng nhớ gõ các lệnh /plugin bên trong Claude Code, không phải trong terminal thường.
D.Tool bị gọi sai tên khi trộn hai đường cài
README cảnh báo: plugin ruflo-core đăng ký công cụ dưới tên như mcp__plugin_ruflo-core_ruflo__memory_store, khác với tên ngắn của đường CLI (memory_store, swarm_init, agent_spawn). Muốn trọn bộ vòng lặp với tên theo đường CLI thì dùng npx ruflo@latest init. Đừng trộn hai cách khi bạn chưa hiểu rõ.
E.Plugin bên ngoài bị nạp hai lần
Với một số plugin bên ngoài (như agentic-qe-fleet, agentdb, agentic-flow), README dặn chỉ cài từ một marketplace. Cài từ cả hai nơi thì mod và lệnh sẽ nạp đôi. Chọn một nơi và gỡ bản còn lại.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Có giấy phép MIT. Repo còn được cập nhật trong ba tháng gần đây. Cộng đồng lớn (khoảng 81588 sao). Có console để nhìn thấy agent làm gì, và bạn tự đặt mức quyền, với các thao tác mạng, tốn tiền, phá huỷ luôn cần xác nhận. Dùng được với Claude Code, Codex và MCP client khác.
Giới hạn. Tư liệu khá nhiều thuật ngữ và nhiều thành phần (48 plugin, hàng trăm công cụ), 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 của bạn, không sandbox. README cũng nói rõ các đoạn demo 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 đúng; phần học là "khái niệm". Hãy tự kiểm chứng kết quả trên dự án của mình.
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ỏ, cứ dùng nó trơn, chưa cần thêm lớp điều phối. Nếu bạn muốn thử nhẹ, chỉ cài ruflo-core và một hai plugin, không thêm file vào dự án. Còn nếu không dùng Claude Code hay Codex thì repo này không phải công cụ dành cho bạn.
Lời khuyên của mình: thử trên một dự án nhỏ hoặc bản sao, giữ Claude control ở read + ask, chạy câu lệnh mẫu của README, rồi mới nâng quyền 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 bạn dùng mã nguồn tự do. Tuy vậy, Ruflo chạy trên Claude Code hoặc Codex, nên chi phí dùng các mô hình đó vẫn tính riêng theo tài khoản của bạn. Tư liệu có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.
Ruflo có chạy được trên Windows không?
Tư liệu README mình đọc được không nêu rõ danh sách hệ điều hành hỗ trợ. Yêu cầu được ghi rõ là Node từ 20.0.0 trở lên và lệnh npx. Bạn nên thử trên một thư mục nhỏ trước và xem trang tài liệu của repo nếu gặp lỗi.
Cần GPU không?
Tư liệu không nêu yêu cầu GPU cho đường cài chính. Có plugin ruflo-ruvector được mô tả là tìm kiếm tăng tốc bằng GPU, nhưng đó là plugin riêng và không bắt buộc.
Ruflo khác gì dùng Claude Code trơn?
Ruflo là lớp harness bao quanh Claude Code: thêm agent chuyên biệt, bộ nhớ qua nhiều phiên, hook định tuyến tác vụ, console theo dõi và khả năng chia việc cho nhiều agent. Bạn vẫn dùng Claude Code như bình thường, phần điều phối chạy nền.
Cài Ruflo có làm thay đổi dự án của tôi không?
Có, nếu đi theo đường npx ruflo@latest init: README nói nó thêm .claude/, .claude-flow/, CLAUDE.md và các file hỗ trợ. Đường chỉ cài plugin trong Claude Code thì không thêm file nào vào workspace. Dùng init với tùy chọn --dry-run chỉ được README nêu cho Grok Build, nên với các đường khác hãy thử trên bản sao trước.
Cho Claude điều khiển console có an toàn không?
Bạn tự đặt mức quyền: read, write, manage hoặc full, cùng chế độ ask hoặc auto. Mặc định hiện là read + ask. Hành động vượt mức quyền bị từ chối, và các thao tác mạng, tốn tiền hay phá huỷ vẫn cần xác nhận kể cả khi để auto. Bạn cũng bấm Take back control để dừng ngay.
Dùng Ruflo với Codex được không?
Được. README ghi: cấu hình client với command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Nếu muốn thiết lập theo dự án, chạy npx ruflo@latest init wizard.


