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 (trước đây là Claude Flow) là một agent harness: lớp công cụ bọc quanh Claude Code hoặc Codex để thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên làm việc và khả năng phối hợp theo nhóm. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Với người đã quen Claude Code thì cài khá dễ, còn phần tính năng nâng cao thì nhiều và cần thời gian làm quen.
Ruflo là một "agent harness" — tạm hiểu là bộ khung làm việc bọc quanh Claude Code và Codex. Model AI lo viết code, còn Ruflo lo phần còn lại: giao việc cho đúng agent, nhớ lại những gì đã làm, chạy nhiều agent phối hợp với nhau, và cho bạn một bảng điều khiển để theo dõi. Trước đây dự án có tên Claude Flow.
Nếu bạn đang dùng Claude Code mà thấy mỗi phiên làm việc lại "quên sạch", hoặc muốn giao một việc lớn (rà soát cả repo, viết test, tóm tắt thay đổi) cho nhiều agent cùng làm, thì đây là loại công cụ dành cho bạn. Người mới hoàn toàn chưa từng mở Claude Code thì nên làm quen Claude Code trước đã.
Điểm đáng giá nhất: README nói rõ bạn không cần học hết hàng trăm công cụ bên trong. 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. Hiện repo có khoảng 81.588 sao và 9.608 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à bảng điều khiển theo dõi chi phí.
I.Ruflo làm được gì
Dưới đây là những phần chính, mình giải thích theo lợi ích thực tế thay vì liệt kê hết.
- Nhiều agent chuyên biệt. README nói bộ cài mang theo hàng chục agent (ghi 98 agent trong bảng so sánh, và "100+" ở phần giới thiệu). Thay vì một agent làm mọi thứ, bạn có agent chuyên review, chuyên test, v.v.
- Swarm — nhóm agent phối hợp. Các agent tự chia việc với nhau cho một nhiệm vụ lớn. Bạn chỉ cần nói "dùng swarm của ruflo để làm việc X".
- Bộ nhớ xuyên phiên. Agent nhớ lại kinh nghiệm từ các lần làm trước. README mô tả bộ nhớ dạng vector (có nhắc HNSW trong chủ đề của repo), nên tìm lại thông tin theo nghĩa chứ không chỉ theo từ khoá.
- Học từ kết quả. Hệ thống hook ghi nhận cách làm thành công để định tuyến tốt hơn lần sau. README cũng tự lưu ý đây là mô tả khái niệm: phần học cục bộ vẫn cần embedding và các module học được cấu hình.
- Bảng điều khiển (console). Theo dõi workflow, agent, model, token và chi phí ngay cạnh Claude Code. Bạn mở bằng lệnh
/ruflo. Có thể xem log từng lần chạy, tìm kiếm, lọc lỗi, phát lại và so sánh. - Cho Claude điều khiển console, nhưng bạn đặt giới hạn. Trong Settings → Claude control có các mức
read,write,manage,full, kèm chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các hành động liên quan mạng, chi tiêu và phá huỷ vẫn phải xác nhận kể cả khi bậtauto. - Hệ plugin lớn. README liệt kê 48 plugin (cộng 3 plugin bên ngoài): swarm, bộ nhớ RAG, tạo test tự động, quét bảo mật, theo dõi chi phí token, quản lý migration cơ sở dữ liệu, tài liệu tự động… Bạn chỉ cài cái cần dùng.
- Liên kết nhiều máy (federation). Agent trên các máy khác nhau có thể giao tiếp an toàn. Đây là tính năng nâng cao, người mới chưa cần đụng.
- Hỗ trợ nhiều máy khách. Ngoài Claude Code còn có Codex và các máy khách MCP khác. README cũng có lệnh riêng cho Grok Build.
II.Cần chuẩn bị gì
Tư liệu chỉ nêu một số yêu cầu rõ ràng:
- Node.js từ 20.0.0 trở lên. File package.json của repo yêu cầu như vậy. Lệnh
npxđi kèm Node nên bạn không cần cài gì thêm. - Claude Code nếu bạn dùng cách cài qua plugin: cần bản 2.1.287 trở lên. Lệnh cài plugin từ terminal cần bản 2.1.292 trở lên.
- Một thư mục dự án để chạy lệnh
inittrong đó. - Codex hoặc máy khách MCP khác nếu bạn không dùng Claude Code.
Về hệ điều hành, tài khoản hay API key: README phần đã có trong tư liệu không nói cụ thể. Bạn cần có sẵn quyền dùng Claude Code (hoặc Codex) như bình thường. Nếu cần thêm khoá cho provider nào thì xem trong thư mục docs của repo.
Các "mod" của Ruflo chạy với quyền của tài khoản bạn và không bị cô lập (sandbox). README khuyên bạn đọc code trước khi cài. Hãy làm đúng như vậy.
III.Cài đặt từng bước
README đưa ra nhiều đường cài. Cách đơn giản nhất cho người mới là chạy init trong dự án.
- 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 vào dự án
- Mở lại Claude CodeKhởi động Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc thậtDán câu lệnh mẫu để thử swarm
- Mở bảng điều khiểnGõ /ruflo trong Claude Code
A.Mở terminal đúng thư mục
Đâ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. Vì vậy hãy mở terminal ngay trong thư mục dự án của bạn (trên Windows có thể dùng PowerShell, trong VS Code thì mở Terminal mới).
cd ten-thu-muc-du-anThay ten-thu-muc-du-an bằng đường dẫn thật của bạn.
B.Chạy lệnh init
npx ruflo@latest initLệnh này tải Ruflo bản mới nhất và thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh trong README, bạn sẽ thấy xuất hiện .claude/, .claude-flow/, CLAUDE.md, các file helper và settings. Vì vậy nếu dự án đang quan trọng, hãy dùng git hoặc sao lưu trước.
Muốn cài có hướng dẫn từng câu hỏi, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent và hook ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn thì hãy đóng rồi mở lại.
D.Cách khác: chỉ cài plugin cho Claude Code
Nếu bạn không muốn Ruflo thêm file vào dự án, README có đường "Claude Code plugins only" (không thêm file nào vào workspace). Gõ các lệnh nà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ừ terminal thường, trên Claude Code 2.1.292 trở lên:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloBảng so sánh trong README cho biết: cách plugin nhẹ hơn (không có hook, chỉ có slash command và vài skill), còn npx ruflo init mới là "vòng lặp đầy đủ" gồm hook, daemon, MCP server. Muốn dùng thật sự thì README khuyên cách init.
E.Dùng với Codex hoặc máy khách MCP khác
Không cần thiết lập dự án. Cấu hình máy khách với command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Nghĩa là máy khách MCP của bạn sẽ chạy lệnh npx -y ruflo@latest mcp start để bật máy chủ MCP của Ruflo. Vị trí điền cấu hình này tuỳ phần mềm bạn dùng, hãy xem tài liệu của phần mềm đó.
F.Chạy console trong terminal thường
Bảng điều khiển cũng 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
Có vài dấu hiệu theo tư liệu:
- Sau
npx ruflo@latest init, thư mục dự án có thêm.claude/,.claude-flow/vàCLAUDE.md. - Mở lại Claude Code rồi gõ
/ruflo. Nếu bảng điều khiển hiện ra là cài thành công. - Với cách cài plugin: gõ
/pluginđể xem các plugin có nằm trong dòng "active mods" không. - Với cách terminal:
npx ruflo tuimở được giao diện console.
Lưu ý trung thực: README không mô tả chi tiết đầu ra của lệnh init, nên mình không đưa ra thông báo mẫu để tránh nói sai. Nếu không thấy gì thay đổi, hãy xem phần lỗi bên dưới.
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ả. Mỗi ví dụ là gợi ý cách dùng, kết quả cụ thể phụ thuộc dự án và model của bạn.
A.Dev nhận repo lạ: rà soát nhanh
Bạn vừa nhận một repo của đồng nghiệp và chưa biết đâu là chỗ dễ hỏng. Sau khi init và mở lại Claude Code, bạn dán đúng câu mẫu trong README:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.Swarm sẽ chia việc: 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 được bản tóm tắt và các file test mới để tự đọc lại. Đừng merge khi chưa xem.
Agent = Model + Harness. Model viết, còn harness cho nó công cụ, trí nhớ và giới hạn để làm việc thật.
Ông T
B.Người làm sản phẩm: tạo "mission" trong console
Bạn không rành code nhưng muốn xem agent làm gì. README có kịch bản làm từng bước:
- Cài console bằng các lệnh plugin ở trên, 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."
- Khi Claude xin tạo mission, bạn xác nhận trong console.
- Kiểm tra mục Missions có mục tiêu mới và Overview có ghi lại hành động.
Lưu ý README nhấn mạnh: tạo mission không có nghĩa tính năng đã được làm xong. Bạn muốn dừng lúc nào thì bấm Take back control.
C.Chủ doanh nghiệp nhỏ có đội dev: theo dõi chi phí token
Nếu đội bạn dùng Claude Code nhiều và lo hoá đơn, README có plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí) và console hiển thị token và chi phí cạnh phiên làm việc. Bạn cài plugin theo cú pháp /plugin install ten-plugin@ruflo rồi mở /ruflo để xem. Cách cấu hình ngân sách cụ thể README phần đã có chưa nêu, hãy xem docs của plugin.
D.Người dùng Codex hoặc công cụ MCP khác
Bạn đang dùng một phần mềm hỗ trợ MCP và muốn có sẵn bộ nhớ cùng điều phối agent mà không cài gì vào dự án. Bạn chỉ cần khai báo máy chủ MCP với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Sau đó các công cụ của Ruflo xuất hiện trong phần mềm đó để agent gọi.
VI.Lỗi hay gặp và cách xử lý
Các lỗi dưới đây là những chỗ rất dễ xảy ra với loại công cụ chạy bằng npx. README không liệt kê chúng thành một mục riêng.
- Lệnh
npxbáo không tìm thấy hoặc Node quá cũ. Kiểm tra bằngnode --version. Repo yêu cầu Node 20 trở lên. Nếu thấp hơn thì cập nhật Node rồi chạy lại. - Chạy
initrồi mà Claude Code không có gì mới. Thường do bạn mở Claude Code ở thư mục khác hoặc chưa khởi động lại. Đóng hẳn, mở lại đúng thư mục đã chạyinit. - Lệnh
/pluginkhông nhận hoặc cài plugin lỗi. Cách plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 cho lệnh từ terminal). Hãy cập nhật Claude Code. Sau khi cài, đừng quên/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. - Claude bị từ chối khi điều khiển console. Đây không phải lỗi: hành động vượt mức quyền bạn đặt sẽ bị từ chối. Muốn cho phép thì nâng mức trong Settings → Claude control, nhưng hãy cân nhắc kỹ.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Có bộ nhớ xuyên phiên và swarm, thứ mà Claude Code đơn thuần không làm sẵn. Có bảng điều khiển để nhìn thấy agent đang làm gì, chi phí bao nhiêu. Có cơ chế quyền rõ ràng (read, write, manage, full; ask hoặc auto). Giấy phép MIT, repo đang hoạt động.
Giới hạn. Dự án rất lớn: README nhắc tới 406 công cụ MCP và 61 lệnh CLI, hàng chục plugin. Người mới dễ choáng. init thêm khá nhiều file vào dự án nên cần dùng git để dễ thu hồi. Các đoạn demo trong README phần lớn dùng dữ liệu mẫu hoặc phát lại khung hình, chúng không chứng minh swarm đã hoàn thành công việc thật hay bộ nhớ nhớ lại đúng. Phần học tự động cần embedding và module cấu hình thêm.
Khi nào chọn cách khác. Nếu bạn chỉ cần nhờ AI sửa vài file nhỏ, Claude Code hoặc Codex thuần là đủ, không cần thêm tầng này. Nếu bạn chỉ thích thử một tính năng riêng lẻ, hãy cài từng plugin thay vì cả bộ init.
Cách mình gợi ý: thử trên một dự án nhỏ, có git, dùng quyền read + ask trước. Quen rồi hãy tă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 bản thân Claude Code, Codex hay nhà cung cấp model bạn dùng đi kèm có thể tính phí riêng. Ruflo có plugin theo dõi token và chi phí, còn chi tiết giá thì tư liệu chưa nêu.
Ruflo có cần GPU không?
Tư liệu không nói Ruflo bắt buộc GPU. Một plugin liên quan (ruflo-ruvector) có nhắc tìm kiếm tăng tốc bằng GPU, nhưng đó là tuỳ chọn. Yêu cầu phần cứng cụ thể chưa có thông tin.
Chạy được trên Windows không?
README phần đã có chưa nêu rõ danh sách hệ điều hành. Điều kiện được nêu là Node 20 trở lên và dùng lệnh npx. Bạn nên thử trên dự án nhỏ, và xem docs của repo nếu gặp vấn đề riêng của Windows.
Ruflo khác gì dùng Claude Code thuần?
Ruflo là lớp bọc quanh Claude Code và Codex. Nó thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua các phiên, hook và bảng điều khiển. Bạn vẫn làm việc trong Claude Code như bình thường.
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: mức quyền cho Claude khi điều khiển console, xác nhận với hành động mạng, chi tiêu và phá huỷ, cùng plugin quét bảo mật. Nhưng các mod chạy bằng quyền tài khoản bạn và không sandbox, nên cần đọc code trước khi cài. Chưa có thông tin về việc dữ liệu được lưu ở đâu ngoài những gì README nêu.
Nên cài bằng plugin hay bằng npx ruflo init?
Plugin không thêm file vào dự án nhưng chỉ có slash command, vài skill và định nghĩa agent. Lệnh init thêm đầy đủ agent, lệnh, skill, MCP server, hook và daemon. README khuyên dùng init cho việc thật, còn plugin hợp để thử từng phần.
Gỡ Ruflo thế nào?
Phần README đã có chưa nêu cách gỡ cài. Vì init thêm các thư mục như .claude/ và .claude-flow/ cùng file CLAUDE.md, bạn nên chạy trong repo có git để dễ xem và hoàn tác thay đổi.


