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 harness mã nguồn mở, giấy phép MIT. Nó bọc quanh Claude Code và Codex để thêm agent chuyên biệt, swarm phối hợp, bộ nhớ lâu dài và bảng điều khiển. Cài chỉ cần một lệnh npx ruflo@latest init trong thư mục dự án, cần Node 20 trở lên.
Ruflo là một "agent harness": lớp công cụ bao quanh Claude Code và Codex để AI không chỉ trả lời từng câu, mà làm việc theo nhóm, nhớ được việc đã làm và có chỗ để bạn theo dõi. Tác giả mô tả ngắn gọn: mô hình AI là người viết, còn harness cung cấp công cụ, bộ nhớ, vòng lặp và giới hạn kiểm soát để nó làm việc thật. Repo hiện có khoảng 81.600 sao và 9.600 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.
Bạn nên xem repo này nếu đang dùng Claude Code hoặc Codex cho công việc lập trình và thấy một phiên chat đơn lẻ là chưa đủ. Ví dụ bạn muốn một nhóm agent cùng rà soát một dự án, viết test, rồi tóm tắt lại. Người mới cũng dùng được, vì README nhấn mạnh sau khi chạy init bạn cứ dùng Claude Code như bình thường. Phần định tuyến việc và phối hợp agent chạy nền thông qua hook.
Điểm đáng giá nhất là cách cài rất ngắn: một lệnh trong thư mục dự án. Ngoài ra còn có tuyến cài chỉ bằng plugin (không thêm file nào vào dự án) và một bảng điều khiển ngay trong Claude Code để xem agent, mô hình, token và chi phí.
ruvnet/ruflo
Ruflo là lớp điều phối bao quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ dùng lại giữa các phiên và bảng điều khiển theo dõi chi phí.
I.Ruflo làm được gì
Theo tư liệu, Ruflo gom nhiều thứ vào một bộ. Bạn không cần học hết, chỉ cần biết những nhóm chính dưới đây.
- Nhiều agent chuyên biệt làm việc theo swarm. README nói bộ cài đầy đủ có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: bạn giao một việc lớn, các agent tự chia nhau thay vì bạn phải điều từng bước.
- Bộ nhớ qua nhiều phiên. Agent ghi nhớ kinh nghiệm từ các tác vụ trước và dùng lại. README cũng ghi rõ: phần 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 định tuyến việc. Sau
init, hook sẽ phân loại tác vụ và học từ những mẫu thành công ở chế độ nền. Bạn không phải nhớ hàng trăm công cụ MCP hay lệnh CLI. - Bảng điều khiển (console) trong Claude Code. Bạn theo dõi workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Có thể mở nhật ký, tìm kiếm, 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. Mức quyền gồm
read,write,manage,full, kèm chế độ duyệtaskhoặcauto. Mặc định hiện tại là read + ask. Các hành động liên quan mạng, chi tiêu hoặc phá hủy vẫn phải xác nhận, kể cả ở chế độauto. - Hệ plugin. Marketplace của repo 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à nhiều nhóm khác. 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,ruflo-aidefencechặn prompt injection. - Liên kết với nhiều công cụ khác. README nói dùng được với Codex và các MCP client khác. Tư liệu cũng có lệnh
npx ruflo init --grokdành cho Grok Build.
II.Cần chuẩn bị gì
Tư liệu nói rõ những điều sau:
- Node.js từ 20.0.0 trở lên. File
package.jsoncủa gói yêu cầu như vậy. Các lệnh cài dùngnpx, đi kèm Node. - Claude Code nếu bạn muốn dùng đường cài đầy đủ hoặc plugin. Riêng tuyến cài chỉ bằng plugin 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. - Codex hoặc MCP client khác nếu bạn không dùng Claude Code. Chỉ cần cấu hình lệnh khởi động MCP (xem phần cài đặt).
- Tài khoản và API key: README phần được cung cấp không nói yêu cầu API key riêng cho Ruflo. Agent vẫn chạy bằng mô hình của Claude Code hoặc Codex mà bạn đang dùng, nên bạn cần tài khoản của công cụ đó. Về hệ điều hành và phần cứng (GPU, RAM), tư liệu chưa nêu yêu cầu cụ thể.
Các mod của Ruflo chạy với đúng quyền tài khoản của bạn và không bị sandbox. README khuyên đọc mã nguồn trước khi cài. Hãy giữ mức quyền Claude control ở read + ask lúc mới thử, và chỉ nâng khi bạn hiểu rõ mình đang cho phép điều gì.
III.Cài đặt từng bước
- Mở terminal đúng thư mụcVào thư mục dự án bạn muốn dùng Ruflo
- Chạy initMột lệnh npx thêm agent, hook, bộ nhớ và MCP server vào dự án
- Mở lại Claude CodeClaude Code nạp cấu hình mới ở lần khởi động kế tiếp
- Giao một việc thậtDán câu lệnh mẫu để thử swarm
- Mở consoleGõ /ruflo trong Claude Code để xem bảng điều khiển
A.Mở terminal trong thư mục dự án
Lệnh init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng chỗ. Nếu chưa có dự án, hãy dùng một thư mục thử nghiệm. Đường dẫn dưới đây chỉ là ví dụ, bạn thay bằng thư mục của mình.
cd ten-thu-muc-du-anB.Chạy lệnh init
Đây là cách cài chính theo README. Bạn chạy trong thư mục dự án:
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. README cho biết đường cài đầy đủ tạo các thư mục .claude/, .claude-flow/ cùng file CLAUDE.md, file hỗ trợ và file cài đặt. Vì vậy hãy dùng git status để xem sau đó nếu dự án của bạn có Git.
Nếu muốn thiết lập tương tác từng câu hỏi, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code trong cùng thư mục
Claude Code sẽ nhận các thứ vừa thêm ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code, hãy thoát ra rồi mở lại trong đúng thư mục đó. Đây là chỗ người mới hay quên.
D.Cách thay thế: cài chỉ bằng plugin
Nếu bạn không muốn thêm file nào vào dự án, dùng tuyến plugin. Các lệnh sau gõ bên trong Claude Code, không phải 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 dùng Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloHãy hiểu đúng sự khác nhau. Theo bảng so sánh trong README, tuyến plugin không tạo file nào trong dự án, không cài hook, và chỉ đăng ký MCP server khi có ruflo-core. Còn npx ruflo init mới cho "vòng lặp đầy đủ": 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon. README khuyên dùng đường này cho việc nghiêm túc.
E.Dùng với Codex hoặc MCP client khác
Không cần thiết lập dự án. Trong phần cấu hình MCP của công cụ đó, đặt command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Tương đương dòng lệnh:
npx -y ruflo@latest mcp startF.Chạy bảng điều khiển ngoài Claude Code
Console cũng chạy độc lập trong terminal thường:
npx ruflo tuiThêm --plain nếu bạn muốn in ra một khung hình duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Sau khi init và mở lại Claude Code, bạn kiểm tra theo thứ tự này:
- Trong thư mục dự án, xem có thư mục
.claude/,.claude-flow/và fileCLAUDE.mdhay không (đây là dấu hiệu của đường cài đầy đủ). - Trong Claude Code, gõ
/ruflo. README nói đây là lệnh mở console. Nếu thấy bảng điều khiển hiện ra, tức là console đã hoạt động. - Nếu bạn cài bằng plugin, gõ
/plugin. README cho biết các mod đang bật sẽ hiện trong dòng "active mods". - Với tuyến terminal độc lập,
npx ruflo tuiphải hiện được giao diện console.
Tư liệu chưa nêu một dòng kết quả cụ thể cho lệnh init, nên bạn dựa vào các dấu hiệu ở trên. Nếu init báo lỗi, bạn xem phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
A.Nhờ swarm rà soát cả dự án
Bối cảnh: bạn là lập trình viên mới nhận một dự án có sẵn, không biết chỗ nào dễ hỏng. Sau khi cài xong và mở lại Claude Code, bạn dán đú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: các agent 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 phần tóm tắt và xem diff trước khi giữ lại. Cách làm này giúp bạn khỏi phải hiểu hết mã nguồn ngay từ đầu.
Agent = Mô hình + Harness: mô hình 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.Tạo một "mission" và giữ quyền kiểm soát
Bối cảnh: bạn là người làm sản phẩm, muốn thử cho Claude điều khiển bảng console mà vẫn an toàn. README mô tả quy trình:
- 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à Overview có ghi lại hành động.
Kết quả: bạn có một mission trong console. README lưu ý rõ: tạo mission không có nghĩa là tính năng đã được làm. Nếu muốn dừng, bấm Take back control và các lệnh sau đó của Claude sẽ bị từ chối cho đến khi bạn cho phép lại.
C.Thử một plugin đơn lẻ, không đụng vào dự án
Bối cảnh: bạn quản lý một repo quan trọng, chưa muốn thêm file lạ vào. Bạn chọn tuyến plugin, chỉ cài thứ cần, ví dụ:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-testgen@rufloTrong README, ruflo-testgen được mô tả là "tìm test còn thiếu và tạo chúng tự động". Tên lệnh cụ thể của từng plugin bạn xem trong /ruflo market (Plugin Catalog) hoặc trong thư mục plugin của repo. Kết quả: bạn dùng thử một khả năng riêng lẻ, không cam kết với cả bộ.
D.Theo dõi chi phí và tiến trình trong terminal
Bối cảnh: bạn lo agent chạy nhiều tốn token. Trong Claude Code, /ruflo hiện tiến trình, mô hình, token và chi phí. Nếu bạn muốn xem ngoài Claude Code:
npx ruflo tui --plainLệnh này in một khung hình ra màn hình, hợp để đưa vào script. Plugin ruflo-cost-tracker còn được README mô tả là có đặt ngân sách và cảnh báo chi phí.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx báo lỗi hoặc không chạy. Kiểm tra Node bằng node --version. Gói yêu cầu Node 20 trở lên, nên bản cũ hơn rất dễ gây lỗi. Cập nhật Node rồi chạy lại npx ruflo@latest init.
Gõ /plugin install mà không có tác dụng hoặc báo không hỗ trợ. Tuyến plugin cần Claude Code 2.1.287 trở lên, còn lệnh claude plugin install ở terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code. Lưu ý các lệnh /plugin ... phải gõ trong Claude Code, không gõ ở terminal thường.
Không thấy /ruflo sau khi cài. Thử hai việc: thoát hẳn Claude Code rồi mở lại trong đúng thư mục đã chạy init, hoặc nếu cài plugin thì chạy /reload-plugins. Sau đó mở /plugin để xem các mod đã nằm trong danh sách bật chưa.
Claude bị từ chối khi điều khiển console. Đây là thiết kế an toàn chứ không phải lỗi. Mức mặc định là read + ask, nên các hành động ghi hoặc cao hơn sẽ bị từ chối. Bạn vào Settings → Claude control để nâng mức, và chỉ nâng khi thật sự cần. Nếu bạn đã bấm Take back control thì phải khôi phục lại quyền.
Plugin bị nạp hai lần, lệnh bị trùng. 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 marketplace, hoặc marketplace gốc của chúng hoặc marketplace ruflo. Cài từ cả hai thì mod và lệnh sẽ nạp hai lần.
VII.Có nên dùng không
Điểm mạnh. Cài đặt gọn (một lệnh), giấy phép MIT, repo đang được cập nhật trong vài tháng gần đây và cộng đồng lớn. Có hai tuyến cài rõ ràng cho hai nhu cầu: thử nhẹ bằng plugin hoặc dùng đầy đủ bằng init. Phần kiểm soát quyền của console được nghĩ khá kỹ: có mức quyền, chế độ hỏi trước và nút lấy lại quyền điều khiển.
Giới hạn. Bộ này rất lớn: hàng chục plugin, hàng trăm công cụ MCP, nên người mới dễ choáng. Cách đỡ nhất là chỉ làm theo phần "một lệnh" rồi dùng Claude Code như thường. README cũng tự nói rõ một số điểm: các đoạn demo dùng dữ liệu mẫu, không phải bằng chứng cho việc swarm đã hoàn thành công việc thật hay bộ nhớ đã nhớ lại đúng. Phần "học" mô tả là một vòng lặp mang tính khái niệm, và vẫn cần embedding cùng module học đã cấu hình. Mod chạy không sandbox với quyền tài khoản của bạn. Tư liệu chưa nêu số liệu chi phí token thực tế khi chạy swarm, nên bạn nên tự theo dõi trong console.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời trong một phiên, với việc nhỏ và không cần nhớ giữa các lần, thì dùng Claude Code thuần là đủ, không cần thêm lớp này. Nếu bạn không muốn thêm file như .claude/ và CLAUDE.md vào dự án, hãy dùng tuyến plugin hoặc thử trong một thư mục tách biệt trước. Với dự án quan trọng, hãy thử trên một nhánh riêng và đọc diff kỹ trước khi giữ thay đổi.
Câu hỏi thường gặp
Ruflo có miễn phí không?
Mã nguồn Ruflo theo giấy phép MIT nên dùng tự do. Tuy nhiên agent vẫn chạy trên mô hình của Claude Code hoặc Codex mà bạn đang dùng, nên chi phí của các dịch vụ đó vẫn áp dụng. Tư liệu chưa nêu cụ thể mức chi phí khi chạy swarm.
Ruflo cài bằng lệnh nào, có khó không?
Đường chính chỉ là một lệnh trong thư mục dự án: npx ruflo@latest init. Sau đó bạn mở lại Claude Code trong cùng thư mục. Bạn cần Node từ bản 20 trở lên.
Dùng Ruflo có cần GPU hoặc cấu hình mạnh không?
Phần tư liệu được cung cấp chưa nêu yêu cầu về GPU hay RAM. Một plugin trong danh sách (ruflo-ruvector) có nhắc đến tìm kiếm tăng tốc bằng GPU, nhưng đó là plugin tùy chọn, không phải điều kiện để cài bộ chính.
Ruflo khác gì dùng Claude Code thông thường?
Ruflo không thay thế Claude Code mà thêm lớp bao quanh nó. Lớp này gồm agent chuyên biệt, swarm phối hợp, bộ nhớ qua các phiên, hook tự định tuyến và bảng điều khiển để theo dõi chi phí. Sau khi init, bạn vẫn dùng Claude Code bình thường.
Cài chỉ bằng plugin và chạy npx ruflo init khác nhau thế nào?
Tuyến plugin không thêm file nào vào dự án và không cài hook, chỉ có lệnh gạch chéo và định nghĩa agent. Còn npx ruflo init cài vòng lặp đầy đủ: 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon, đồng thời tạo các thư mục như .claude/ và .claude-flow/. README khuyên đường init cho việc dùng nghiêm túc.
Dùng Ruflo với Codex hoặc công cụ ngoài Claude Code được không?
Được. README nói Codex và các MCP client khác dùng được, bằng cách cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Tư liệu cũng có lệnh npx ruflo init --grok cho Grok Build.
Cho Claude điều khiển console có an toàn không?
Mặc định là read + ask, tức Claude chỉ được đọc và phải hỏi bạn. Hành động liên quan mạng, chi tiêu hoặc phá hủy vẫn cần xác nhận kể cả ở chế độ auto. Bạn có thể bấm Take back control để dừng. Riêng các mod thì chạy với quyền tài khoản của bạn và không bị sandbox, nên cần đọc mã trước khi cài.


