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à bộ công cụ bọc quanh Claude Code và Codex, giúp nhiều AI agent phối hợp thành đội, có bộ nhớ giữa các phiên và có hooks tự định tuyến công việc. 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 đã dùng Claude Code thì cài khá dễ, nhưng bộ tính năng rất rộng nên nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một “agent meta-harness”: lớp công cụ bọc quanh Claude Code và Codex để AI không chỉ trả lời từng câu mà còn làm việc theo đội. Hiểu đơn giản: mô hình AI là người viết, còn harness là bàn làm việc đầy đủ dụng cụ quanh người đó. Ruflo thêm vào bàn làm việc ấy các agent chuyên biệt, bộ nhớ, vòng lặp và các lớp kiểm soát.
Bạn nên xem repo này nếu đang dùng Claude Code (hoặc Codex) và thấy một agent đơn lẻ chưa đủ. Ví dụ bạn muốn một nhóm agent cùng rà soát dự án, viết test, rồi tóm tắt lại những gì đã đổi. Người mới cũng dùng được, vì tác giả nói rõ bạn không cần học hết hàng trăm công cụ. Sau khi chạy init, bạn cứ dùng Claude Code như bình thường, còn hooks sẽ tự định tuyến tác vụ và học từ các lần làm thành công.
Điểm đáng giá nhất là cách cài rất gọn: một lệnh npx là xong phần nền. Repo hiện có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, ngôn ngữ chính là TypeScript và vẫn được cập nhật trong vài tháng gần đây.
ruvnet/ruflo
Ruflo là lớp “harness” bọc quanh Claude Code và Codex: thêm agent, bộ nhớ, hooks và MCP server chỉ với một lệnh npx.
I.Ruflo làm được gì
Theo README, Ruflo là phần “thực thi” xung quanh Claude Code và Codex. Dưới đây là những nhóm tính năng đáng quan tâm nhất, nói theo lợi ích thực tế.
A.Đội agent làm việc cùng nhau
Ruflo đi kèm hàng trăm agent chuyên biệt (README nhắc “100+”, bảng so sánh ghi 98 agent). Chúng được tổ chức thành “swarm”, tức một nhóm agent chia việc cho nhau. Thay vì bạn tự giao từng việc nhỏ, bạn mô tả mục tiêu lớn và để nhóm tự phân công.
B.Bộ nhớ qua nhiều phiên
Agent có bộ nhớ, nên kinh nghiệm từ lần làm trước được dùng lại cho lần sau. README còn nói bộ nhớ này phản hồi ngược vào bước định tuyến tác vụ. Có các plugin riêng cho việc này, ví dụ lưu và khôi phục bộ nhớ giữa các phiên, hay tìm kiếm thông minh kết hợp nhiều kiểu tìm.
Lưu ý trung thực: README ghi rằng vòng học này là mô hình khái niệm. Phần truy xuất vector cục bộ có thể chạy không cần LLM, nhưng vẫn cần embeddings và các module học đã được cấu hình.
C.Hooks tự định tuyến
Sau init, hệ thống hooks chạy nền: định tuyến tác vụ, học từ mẫu làm tốt và điều phối agent. Với người mới, đây là phần “đỡ phải nghĩ” nhất.
D.Bảng điều khiển ngay cạnh Claude Code
Plugin ruflo-console là một “cockpit”: theo dõi workflow, agent, mô hình, token và chi phí. Bạn có thể mở log và kết quả của 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. Gõ /ruflo trong Claude Code để mở.
E.Để Claude lái, bạn đặt giới hạn
Bạn có thể cho Claude điều khiển bảng điều khiển ở một trong bốn mức: read, write, manage hoặc full, kèm chế độ phê duyệt ask hoặc auto. Mặc định hiện tại là read + ask. Hành động vượt quyền sẽ bị từ chối. Các hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận kể cả khi để auto.
F.Hệ sinh thái plugin lớn
README liệt kê 48 plugin, chia nhóm: điều phối, bộ nhớ, học và trí tuệ, kiểm thử chất lượng, bảo mật, kiến trúc, DevOps và các nhóm khác. Một vài ví dụ: ruflo-testgen tìm test còn thiếu và tạo ra, ruflo-security-audit quét lỗ hổng, ruflo-cost-tracker theo dõi token và đặt ngân sách, ruflo-docs tạo và duy trì tài liệu.
G.Liên kết nhiều máy (federation)
Theo README, agent trên các máy khác nhau có thể trao đổi với nhau một cách an toàn mà không làm lộ dữ liệu. Tính năng này dành cho nhu cầu nâng cao, người mới có thể bỏ qua lúc đầu.
II.Cần chuẩn bị gì
- Node.js từ 20.0.0 trở lên. File
package.jsoncủa repo yêu cầu như vậy. README chưa hướng dẫn cách cài Node, bạn lấy bản cài từ trang chủ Node.js. - Claude Code nếu bạn dùng đường cài chính. Tác vụ mẫu trong README là mở Claude Code trong cùng thư mục dự án.
- Claude Code bản 2.1.287 trở lên nếu bạn chọn đường cài chỉ bằng plugin. Lệnh cài từ terminal cần bản 2.1.292 trở lên.
- Một thư mục dự án để chạy lệnh cài. README nói rõ: chạy trong thư mục dự án của bạn.
- Codex hoặc client MCP khác cũng dùng được, nếu client cho phép khai báo lệnh MCP server.
Về tài khoản, API key và phần cứng: README (phần mình có) chưa nêu yêu cầu cụ thể. Hệ điều hành cũng chưa được nói rõ. Chi phí gọi mô hình tuỳ vào công cụ AI bạn đang dùng, không phải thứ Ruflo ghi sẵn.
III.Cài đặt từng bước
README đưa ra nhiều đường cài. Mình hướng dẫn đường chính trước, rồi hai đường phụ.
- Kiểm tra NodeBảo đảm máy có Node.js từ bản 20 trở lên
- Mở terminal đúng chỗVào thư mục dự án mà bạn muốn gắn Ruflo
- Chạy initGõ một lệnh npx để thêm agent, hooks, bộ nhớ và MCP server
- Mở lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Gõ /rufloMở bảng điều khiển để xác nhận đã chạy
A.Kiểm tra Node
Trước tiên hãy chắc máy có Node bản 20 trở lên. Bạn có thể mở terminal và gõ lệnh dưới đây để xem phiên bản. Lệnh này là lệnh phổ thông của Node, không nằm trong README của Ruflo.
node --versionNếu số hiện ra nhỏ hơn 20, hãy cập nhật Node rồi mới tiếp tục.
B.Mở terminal đúng thư mục dự án
Đây là chỗ người mới hay vấp nhất. init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong dự án của mình. Ví dụ:
cd duong-dan-toi-du-an-cua-banHãy thay duong-dan-toi-du-an-cua-ban bằng đường dẫn thật. Nếu bạn dùng Windows, bạn có thể mở thư mục dự án rồi mở terminal từ chính thư mục đó.
C.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initnpx tải Ruflo bản mới nhất rồi chạy lệnh init. Theo README, lệnh này thêm agent, hooks, bộ nhớ và MCP server của Ruflo vào dự án. Bảng so sánh trong README cho biết đường này tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, các file helper và settings. Vì vậy hãy chạy trong dự án bạn đã commit hoặc sao lưu, để dễ xem Ruflo đã thêm gì.
Nếu muốn thiết lập theo từng câu hỏi, README có lệnh sau:
npx ruflo@latest init wizardD.Mở lại Claude Code
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent, hooks, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code, hãy thoát rồi mở lại.
E.Đường cài khác: chỉ dùng plugin của Claude Code
Đường này không thêm file nào vào dự án và cần Claude Code từ 2.1.287 trở lên. Bạn 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
/rufloLệnh đầu thêm “chợ” plugin của Ruflo. Ba lệnh install cài lõi, bảng điều khiển và các mod. /reload-plugins nạp lại để dùng ngay. Từ terminal, với Claude Code 2.1.292 trở lên, README ghi một lệnh tương đương:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloCần biết thêm: đường chỉ-plugin nhẹ hơn nhưng ít tính năng hơn. README so sánh rằng đường npx ruflo init mới có “vòng Ruflo” đầy đủ (agent, lệnh, skill, MCP server, hooks, daemon) và khuyên dùng cho công việc thật.
F.Đường cài khác: Codex hoặc client MCP khác
Bạn không cần thiết lập dự án. Chỉ cần khai báo trong client:
- command:
npx - arguments:
["-y", "ruflo@latest", "mcp", "start"]
Dạng JSON dưới đây chỉ minh hoạ hai giá trị trên. Mỗi client có định dạng file cấu hình khác nhau, nên bạn hãy xem tài liệu của client đó để biết đặt vào đâu.
["-y", "ruflo@latest", "mcp", "start"]Mod của Ruflo chạy với quyền của tài khoản bạn và không có sandbox. README khuyên bạn đọc code của mod trước khi cài. Tương tự, hãy để mức điều khiển của Claude ở read + ask khi mới làm quen, và chỉ nâng lên khi bạn hiểu rõ mình đang cho phép điều gì.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một đoạn “output mẫu” cố định, nhưng đưa ra các dấu hiệu rõ ràng:
- Sau
npx ruflo@latest init, thư mục dự án có thêm các mục như.claude/,.claude-flow/vàCLAUDE.md. - Khởi động lại Claude Code rồi gõ
/ruflo. Nếu bảng điều khiển mở ra, bạn đã cài thành công. - Nếu cài bằng plugin, gõ
/pluginđể xem. README nói các plugin sẽ hiện trong dòng “active mods”. - Muốn thử ngoài Claude Code, chạy giao diện terminal độc lập:
npx ruflo tuiThêm cờ --plain để in ra đúng một khung hình, tiện cho script:
npx ruflo tui --plainCuối cùng, thử một tác vụ thật như phần dưới để chắc rằng agent hoạt động.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo ví dụ README mô tả. Mình không hứa kết quả cụ thể vì nó tuỳ vào dự án của bạn.
A.Rà soát một dự án đang chạy
Bối cảnh: bạn là lập trình viên nhận lại một repo cũ, chưa ai dám đụng. Bạn chạy npx ruflo@latest init trong thư mục repo, mở lại Claude Code, rồi dán 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.Câu này yêu cầu swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Kết quả bạn nhận là một bản tóm tắt thay đổi để tự đọc lại. Hãy xem lại phần test do agent viết trước khi giữ.
Agent = Mô hình + Harness. Mô hình 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.Giao việc có kiểm soát qua bảng điều khiển
Bối cảnh: bạn là quản lý sản phẩm, muốn thử để Claude tạo “mission” nhưng chưa muốn nó tự làm bừa. Làm theo các bước README gợi ý:
- Cài
ruflo-console, mở/ruflo, vào Settings → Claude control và chọn write + ask. - Gõ yêu cầu cụ thể: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
- Khi 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 và Overview có ghi lại hành động.
Kết quả: một mission được tạo, nằm trong danh sách để bạn theo dõi. README nhấn mạnh rằng tạo mission không có nghĩa tính năng đã được làm. Nếu cần dừng, bấm Take back control, các lời gọi sau của Claude sẽ bị từ chối cho tới khi bạn trả quyền.
C.Dùng Ruflo từ Codex hoặc công cụ MCP khác
Bối cảnh: nhóm bạn dùng Codex chứ không phải Claude Code. Bạn không cần gắn gì vào dự án, chỉ khai báo MCP server với lệnh npx và các tham số -y, ruflo@latest, mcp, start như phần cài đặt ở trên. Sau đó client có thể gọi công cụ của Ruflo. Mình chưa có tư liệu về danh sách công cụ cụ thể sẽ hiện ra ở từng client, nên bạn hãy kiểm tra trong chính client.
D.Theo dõi chi phí và tiến độ bằng cửa sổ terminal
Bối cảnh: bạn muốn xem tiến độ agent mà không mở Claude Code. Chạy npx ruflo tui để xem bảng điều khiển ngay trong terminal. Nếu cần đưa vào script, dùng --plain để in một khung hình duy nhất. Muốn theo dõi token và đặt ngân sách, README có plugin ruflo-cost-tracker với mô tả “track token usage, set budgets, get cost alerts”.
VI.Lỗi hay gặp và cách xử lý
A.Claude Code không thấy agent hay lệnh /ruflo
Nguyên nhân hay gặp là chưa khởi động lại. README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn rồi mở lại trong đúng thư mục bạn đã chạy init. Nếu dùng plugin, chạy /reload-plugins.
B.Lệnh npx báo lỗi hoặc không chạy
Thường do Node chưa cài hoặc quá cũ. Repo yêu cầu Node 20 trở lên. Chạy node --version để kiểm tra rồi cập nhật nếu cần. Lệnh npx đi cùng Node nên không cần cài riêng.
C.Lệnh plugin bị từ chối vì Claude Code quá cũ
Đường cài plugin cần Claude Code 2.1.287 trở lên, cò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 khi thử lại.
D.Plugin tải hai lần hoặc 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ỉ nên cài từ một marketplace. Nếu bật từ cả hai, mod và lệnh sẽ tải hai lần. Hãy gỡ một bản và giữ lại một.
E.Claude từ chối thao tác trong bảng điều khiển
Đây thường không phải lỗi. Mức quyền mặc định là read + ask, nên hành động ghi hoặc quản lý bị từ chối. Vào Settings → Claude control để nâng mức theo ý bạn, và nhớ rằng thao tác liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả khi để auto.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Dùng MIT nên rộng rãi cho cá nhân và doanh nghiệp. Hỗ trợ cả Claude Code lẫn Codex qua MCP. Có bảng điều khiển với cơ chế giới hạn quyền rõ ràng. Hệ sinh thái plugin phong phú và repo vẫn được cập nhật.
Giới hạn. Bộ tính năng rất rộng (README nhắc hàng trăm công cụ MCP và hàng chục lệnh CLI), nên người mới dễ bị ngợp. Đườ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 và không có sandbox. Một số phần, như vòng học, README tự nhận là mô hình khái niệm. Các đoạn demo trong README dùng dữ liệu mẫu, chưa chứng minh được việc hoàn thành swarm thật hay khả năng nhớ lại.
Khi nên chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời vài việc đơn giản, bạn chưa cần Ruflo. Nếu muốn thử nhẹ, hãy dùng đường chỉ-plugin để không thêm file vào dự án. Nếu bạn cần chắc chắn về an toàn dữ liệu và chi phí, hãy bắt đầu trong một repo thử nghiệm, giữ mức quyền read + ask và đọc kỹ tài liệu bảo mật của repo trước khi dùng cho dự án quan trọng.
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 được dùng và sửa mã. Tư liệu mình có chưa nói gì về chi phí gọi mô hình AI, phần này tính theo công cụ bạn dùng như Claude Code hay Codex. README có plugin theo dõi token và đặt ngân sách nếu bạn muốn kiểm soát.
Ruflo cài như thế nào, có khó không?
Đường chính chỉ cần một lệnh `npx ruflo@latest init` trong thư mục dự án, rồi mở lại Claude Code. Bạn cần Node từ bản 20 trở lên. Ngoài ra còn đường chỉ-plugin và đường cấu hình MCP cho Codex.
Ruflo có chạy được trên Windows không?
Tư liệu mình có chưa nói rõ về hệ điều hành được hỗ trợ. Điều README yêu cầu là Node 20 trở lên và Claude Code. Bạn nên tự thử trên một dự án thử trước khi dùng thật.
Có cần GPU hoặc cấu hình máy mạnh không?
README ở phần mình có không nêu yêu cầu GPU cho đường cài chính. Một plugin riêng là ruflo-ruvector có nhắc tìm kiếm tăng tốc bằng GPU, nhưng đó là phần tuỳ chọn. Yêu cầu phần cứng cụ thể thì chưa có thông tin.
Dữ liệu và quyền truy cập có an toàn không?
Bảng điều khiển có mức quyền read, write, manage, full và chế độ ask hoặc auto, mặc định là read + ask. Hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả khi để auto. Tuy nhiên mod chạy với quyền tài khoản của bạn và không có sandbox, nên bạn nên đọc code trước khi cài.
Ruflo khác gì dùng Claude Code thông thường?
Claude Code là công cụ để mô hình làm việc, còn Ruflo là lớp bao quanh thêm agent chuyên biệt, swarm, bộ nhớ, hooks và bảng điều khiển. Sau khi chạy init bạn vẫn dùng Claude Code như thường, còn hooks tự định tuyến và học trong nền.
Dùng Ruflo với Codex hoặc công cụ khác ngoài Claude Code được không?
Được theo README. Bạn khai báo command là `npx` với tham số `-y`, `ruflo@latest`, `mcp`, `start` trong client hỗ trợ MCP. README cũng có lệnh `npx ruflo init --grok` cho Grok Build, nhưng mình chưa có chi tiết cách dùng nên bạn xem hướng dẫn trong repo.


