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à lớp điều phối đặt quanh Claude Code và Codex. Nó thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên làm việc, hook và MCP server vào dự án của bạn. Cài chỉ cần một lệnh npx trong thư mục dự án, cần Node 20 trở lên.
Ruflo là một bộ khung điều phối (README gọi là agent harness) đặt quanh Claude Code và Codex. Nói đơn giản: Claude Code vẫn là người viết code, còn Ruflo cho nó thêm công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát để làm việc lớn hơn một câu hỏi một câu trả lời. Repo hiện có khoảng 81.588 sao và 9.608 fork, giấy phép MIT, viết chủ yếu bằng TypeScript.
Vấn đề nó giải quyết khá quen thuộc. Khi giao một việc dài cho AI (rà soát cả repo, viết test, sửa lỗi), bạn phải tự nhắc lại bối cảnh, tự chia việc, tự kiểm tra. Ruflo thêm một lớp để nhiều agent chia nhau làm, nhớ lại kinh nghiệm từ các lần trước, và có chỗ để bạn theo dõi từng bước.
Ai nên dùng? Lập trình viên đã dùng Claude Code hoặc Codex và muốn thử làm việc theo kiểu nhóm agent. Người mới cũng thử được: README nói bạn không cần học hết hàng trăm công cụ, chỉ cần chạy init rồi dùng Claude Code như bình thường. Điểm đáng giá nhất là cách cài rất gọn (một lệnh) và có lựa chọn nhẹ hơn là chỉ cài plugin, không thêm file nào vào dự án.
ruvnet/ruflo
Ruflo là bộ khung (harness) thêm agent, bộ nhớ, hook và MCP server cho Claude Code và Codex, cài bằng một lệnh npx.
I.Ruflo làm được gì
Dưới đây là những tính năng chính theo README, giải thích theo lợi ích thực tế.
- Nhiều agent chuyên biệt và swarm. README nói bộ cài đầy đủ có 98 agent, hơn 60 lệnh và 30 skill. Swarm là cách cho nhiều agent làm chung một việc như một nhóm, thay vì một mình Claude làm tuần tự.
- Bộ nhớ qua nhiều phiên. Agent nhớ lại kết quả của các lần làm trước, nên lần sau bạn đỡ phải giải thích lại. README mô tả đây là bộ nhớ có tìm kiếm vector, các plugin như
ruflo-agentdb,ruflo-rag-memory,ruflo-rvfphục vụ phần này. - Hook tự định tuyến việc. Sau khi
init, hệ thống hook tự chuyển tác vụ cho đúng agent và học từ các mẫu làm việc thành công, chạy ngầm trong lúc bạn dùng Claude Code như thường. - MCP server. Codex hoặc bất kỳ ứng dụng nào hỗ trợ MCP đều trỏ vào được, nên không bị khóa riêng với Claude Code.
- Bảng điều khiển (console). Mở bằng lệnh
/ruflotrong Claude Code. Bạn xem được workflow, agent, model, token và chi phí cạnh Claude Code; xem log, tìm kiếm, lọc lỗi, phát lại và so sánh các lần chạy. - Cho Claude lái bảng điều khiển nhưng có giới hạn. Trong Settings → Claude control, bạn chọn mức
read,write,managehoặcfull, và kiểu duyệtaskhoặcauto. Mặc định hiện là read + ask. Các hành động dùng mạng, tốn tiền hoặc phá hủy vẫn phải xác nhận ngay cả khi đểauto. - 48 plugin chia theo nhóm. 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,ruflo-docstạo và duy trì tài liệu,ruflo-federationcho agent ở các máy khác nhau cộng tác an toàn. - Chế độ chạy trong terminal thường. Console chạy độc lập được bằng
npx ruflo tui, không cần Claude Code.
II.Cần chuẩn bị gì
Chỉ liệt kê những gì tư liệu nói:
- Node.js từ phiên bản 20.0.0 trở lên. Đây là yêu cầu trong
package.json. Lệnhnpxđi kèm Node. - Claude Code, nếu bạn dùng cách cài vào dự án hoặc cách plugin. Cách chỉ-plugin cần Claude Code 2.1.287 trở lên; lệnh cài plugin từ terminal cần 2.1.292 trở lên.
- Codex hoặc ứng dụng MCP khác, nếu bạn không dùng Claude Code.
- Tài khoản và API key cho dịch vụ AI bạn đang dùng (Claude Code, Codex…) thì bạn đã có sẵn khi dùng các công cụ đó. README phần được cung cấp không nói thêm key riêng nào của Ruflo, và cũng chưa nêu yêu cầu hệ điều hành hay phần cứng cụ thể.
Các mod của Ruflo chạy với quyền tài khoản của bạn và không bị cô lập (sandbox). README khuyên đọc mã nguồn trước khi cài. Cũng nên theo dõi chi phí token, vì nhiều agent chạy cùng lúc có thể tốn hơn một cuộc trò chuyện đơn.
III.Cài đặt từng bước
README có nhiều đường cài. Cách chính là chạy init trong thư mục dự án. Cách nhẹ là cài plugin, không thêm file vào dự án.
- Kiểm tra NodeĐảm bảo máy có Node 20 trở lên
- Mở terminal đúng chỗVào thư mục dự án của bạn
- Chạy initThêm agent, hook, bộ nhớ và MCP server vào dự án
- Mở lại Claude CodeClaude Code nhận cấu hình mới ở lần khởi động kế tiếp
- Thử một việc thậtGiao Claude một nhiệm vụ dùng swarm
A.Kiểm tra Node
Mở terminal (trên Windows là PowerShell, trên máy khác là Terminal) và xem phiên bản Node. Lệnh node --version là lệnh phổ thông; kết quả cần từ v20 trở lên. Nếu thấp hơn, bạn cần cập nhật Node trước.
node --versionB.Mở terminal trong thư mục dự án
Chỗ người mới hay vấp nhất: lệnh init ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong thư mục dự án cần dùng, đừng đứng ở thư mục chứa nhiều dự án. Nếu chưa có dự án, bạn có thể lấy một repo về thử (thay bằng repo của bạn):
git clone https://github.com/<tên-chủ>/<tên-repo>.git
cd <tên-repo>C.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initREADME giải thích init thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh, cách này tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md cùng một số file hỗ trợ và cài đặt trong dự án. Nghĩa là nó thay đổi dự án của bạn: nếu dự án có Git, bạn nên commit trước để dễ xem lại những gì được thêm.
Muốn thiết lập có hỏi đáp từng bước, README ghi lệnh:
npx ruflo@latest init wizardNếu bạn dùng Grok Build, README ghi npx ruflo init --grok, lệnh này chỉ ghi file trong dự án; thêm --dry-run để xem trước mà chưa ghi gì.
D.Mở lại Claude Code
Mở Claude Code trong cùng thư mục. README nói 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 và mở lại.
E.Cách khác: chỉ cài plugin trong Claude Code
Cách này không thêm file nào vào dự án và cần Claude Code 2.1.287 trở lên. Gõ từng dòng trong khung chat của 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), README ghi:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloBảng so sánh trong README nói rõ khác biệt: cách plugin nhẹ, không để file trong thư mục làm việc, chỉ có lệnh gạch chéo, vài skill và định nghĩa agent; hook thì không được cài. Cách init cho trọn bộ gồm MCP server, hook và daemon, README khuyên dùng cho việc nghiêm túc.
F.Cách khác: dùng với Codex hoặc ứng dụng MCP khác
Trong phần cấu hình MCP của ứng dụng, điền command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Nó tương đương với việc chạy npx -y ruflo@latest mcp start. Cách này không cần thiết lập dự án.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh kiểm tra duy nhất, nhưng có mấy dấu hiệu rõ:
- Sau
init, trong thư mục dự án xuất hiện.claude/,.claude-flow/vàCLAUDE.md(theo bảng so sánh cách cài). - Mở lại Claude Code rồi gõ
/ruflo: nếu bảng điều khiển hiện ra là Ruflo đã được nhận. Cách này áp dụng cho cả càiinitlẫn cài plugin. - Với cách plugin, mở
/pluginvà xem các mod có nằm trong dòng mod đang hoạt động hay không. - Muốn thử giao diện terminal độc lập:
npx ruflo tui. Thêm--plainđể in ra đúng một khung hình, tiện cho script.
npx ruflo tuiNếu /ruflo báo không có lệnh, quay lại bước mở lại Claude Code hoặc chạy /reload-plugins (với cách plugin).
V.Dùng vào việc thật
Các tình huống dưới đây bám theo ví dụ và khả năng README mô tả. Kết quả thực tế còn phụ thuộc dự án và model bạn dùng.
A.Lập trình viên rà soát một dự án lạ
Bạn vừa nhận một repo cũ và chưa biết chỗ nào 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.Kết quả mong đợi: Claude dùng swarm để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã thay đổi. Bạn vẫn nên đọc lại test và diff trước khi nhận.
Bạn vẫn viết code như thường; Ruflo lo phần phối hợp phía sau.
Ông T
B.Người quản lý muốn xem việc AI đang làm và tốn bao nhiêu
Bạn không rành code nhưng đang cho nhóm dùng Claude Code và muốn nhìn tổng thể. Cài ruflo-console, mở /ruflo. Bảng điều khiển hiển thị workflow, agent, model, token và chi phí cạnh Claude Code. Khi có lần chạy bị lỗi, bạn mở log và kết quả của agent để lọc ra lần lỗi. Nếu muốn có cảnh báo chi phí, README liệt kê plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo).
C.Tạo một mission bằng cách nhờ Claude điều khiển console
Đây là quy trình README mô tả từng bước, rất hợp để làm quen:
- Mở
/ruflo, chọn Settings → Claude control → 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.
- Kiểm tra mục Missions có mục tiêu mới và Overview ghi lại hành động.
- Muốn dừng: bấm Take back control.
Lưu ý README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Đây chỉ là việc ghi nhận mục tiêu.
D.Dùng chung với Codex hoặc công cụ MCP khác
Nếu nhóm bạn dùng Codex, bạn cấu hình MCP server như phần cài đặt ở trên. Khi đó Codex gọi được các công cụ của Ruflo mà không cần thiết lập dự án. Muốn thiết lập dự án có hướng dẫn, chạy npx ruflo@latest init wizard.
VI.Lỗi hay gặp và cách xử lý
README phần được cung cấp không có mục xử lý lỗi, nên các mục dưới đây là những tình huống rất dễ gặp với loại công cụ này.
- Lệnh
npxkhông chạy hoặc báo thiếu Node. Cài hoặc cập nhật Node lên 20 trở lên rồi mở terminal mới. /ruflohoặc/pluginkhông nhận. Có thể Claude Code của bạn cũ. Cách plugin cần 2.1.287 trở lên (lệnh trong terminal cần 2.1.292). Cập nhật Claude Code, rồi chạy/reload-plugins.- Đã
initnhưng Claude Code không thấy gì. Thoát hẳn và mở lại Claude Code đúng trong thư mục đã chạyinit. Kiểm tra thư mục có.claude/vàCLAUDE.md. - Plugin cài từ hai nơi bị nạp hai lần. README cảnh báo với các plugin bên ngoài (agentic-qe-fleet, agentdb, agentic-flow): chỉ cài từ một marketplace, không cài cả hai nơi.
- Gọi công cụ MCP bằng tên lạ. README nói
ruflo-coređăng ký công cụ dưới tên dạngmcp__plugin_ruflo-core_ruflo__memory_store, khác tên ngắn của cáchinit. Đây là khác biệt giữa hai đường cài, không phải lỗi. Cần đủ bộ công cụ theo tên ngắn thì dùnginit. - Claude bị từ chối khi điều khiển console. Do mức quyền đang thấp (mặc định read + ask). Nâng mức trong Settings nếu bạn thực sự muốn, và hiểu rằng hành động dùng mạng, tốn tiền, phá hủy vẫn cần xác nhận.
VII.Có nên dùng không
Điểm mạnh. Cài rất nhanh bằng một lệnh. Có hai đường (nhẹ bằng plugin, đầy đủ bằng init) nên thử không tốn nhiều. Dùng được với cả Claude Code, Codex và ứng dụng MCP khác. Giấy phép MIT, repo còn được cập nhật trong vài tháng gần đây. Phần quyền của Claude control được thiết kế có kiểm soát: mặc định chỉ đọc, hành động nhạy cảm luôn hỏi.
Giới hạn. Hệ thống rất lớn: README nhắc 406 công cụ MCP, 61 lệnh CLI và 48 plugin, người mới dễ choáng, dù README bảo không cần học hết. init thêm nhiều file vào dự án. Các mod không được sandbox. README cũng tự nói rõ một số bả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 việc nhớ lại bộ nhớ, nên đừng kỳ vọng quá mức. Tôi cũng chưa có thông tin về chi phí chạy thực tế.
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 nhỏ, dùng Claude Code thuần là đủ. Nếu muốn thử nhẹ, hãy bắt đầu bằng cách plugin (không thêm file vào dự án). Khi cần cả hook và MCP đầy đủ, chuyển sang npx ruflo@latest init trên một dự án thử trước, đã commit sạch, rồi mới áp 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 mã nguồn dùng tự do. Tuy nhiên bạn vẫn trả chi phí cho dịch vụ AI bạn dùng bên dưới như Claude Code hay Codex. Tư liệu chưa có thông tin về gói trả phí riêng của Ruflo.
Cài Ruflo cần những gì?
Cần Node.js từ 20.0.0 trở lên. Nếu dùng cách plugin thì cần Claude Code 2.1.287 trở lên. Tư liệu chưa nêu yêu cầu về hệ điều hành hay phần cứng.
Ruflo cài bằng lệnh nào?
Chạy `npx ruflo@latest init` trong thư mục dự án, rồi mở lại Claude Code. Muốn thiết lập có hướng dẫn thì dùng `npx ruflo@latest init wizard`. Còn cách chỉ cài plugin trong Claude Code mà không thêm file vào dự án.
Hai cách cài plugin và init khác nhau thế nào?
Plugin nhẹ, không để file trong dự án, chỉ có lệnh gạch chéo, vài skill và định nghĩa agent, không có hook. Cách init cho đầy đủ: 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon, nhưng thêm các thư mục như .claude/ và .claude-flow/ cùng file CLAUDE.md vào dự án.
Dùng được với Codex không?
Được. README nói Codex và các ứng dụng MCP khác dùng được: cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Không cần thiết lập dự án.
Claude có tự ý làm việc nguy hiểm trên console không?
README nói mức mặc định hiện là read + ask. Hành động vượt quyền bị từ chối, còn hành động dùng mạng, tốn tiền hoặc phá hủy luôn cần xác nhận kể cả ở chế độ auto. Bạn có thể bấm Take back control để dừng.
Có chạy được mà không cần Claude Code không?
Có một phần. Console chạy độc lập trong terminal bằng `npx ruflo tui`, và thêm `--plain` để in một khung hình cho script. Các ứng dụng MCP khác cũng dùng được máy chủ MCP của Ruflo.


