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 và Codex để thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên và máy chủ MCP. 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. Dùng cơ bản không khó, nhưng hệ thố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" cho Claude Code và Codex: một lớp công cụ đặt quanh mô hình AI để nó có thêm agent chuyên biệt, bộ nhớ, vòng lặp tự cải thiện và các chốt kiểm soát. Tác giả mô tả ngắn gọn: mô hình là phần biết viết, còn harness là phần đưa cho mô hình công cụ, trí nhớ và luật chơi để nó làm việc được thật. Ruflo là phần harness đó. Dự án vốn có tên Claude Flow, nay đổi tên thành Ruflo, giấy phép MIT, hiện có khoảng 81.588 sao và 9.608 fork trên GitHub.
Bạn nên đọc bài này nếu đã dùng Claude Code (hoặc Codex) và thấy một agent đơn lẻ làm việc lớn hơi chật chội: quên ngữ cảnh giữa các phiên, không biết chia việc, khó theo dõi chi phí. Ruflo cho phép nhiều agent phối hợp thành một "swarm" (đàn agent), nhớ lại kinh nghiệm cũ và có bảng điều khiển để bạn nhìn thấy chuyện gì đang diễn ra.
Điểm đáng giá nhất là cách cài: một lệnh npx ruflo@latest init trong thư mục dự án, mở lại Claude Code là dùng được. README nói rõ bạn không cần học hết hàng trăm công cụ MCP hay hàng chục lệnh CLI. Sau init, bạn cứ dùng Claude Code như bình thường, còn hệ thống hook sẽ tự định tuyến tác vụ và điều phối agent ở phía sau.
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, hook và MCP server chỉ với một lệnh init.
I.Ruflo làm được gì
Dưới đây là những nhóm tính năng chính, theo đúng những gì README mô tả.
A.Thêm agent, hook, bộ nhớ và MCP server vào dự án
Lệnh init bổ sung agent, hook, bộ nhớ và một MCP server vào thư mục dự án. Lợi ích thực tế: bạn không phải tự cấu hình từng thứ. Lần sau Claude Code khởi động, nó nhận ra các thành phần này luôn. README cho biết bản cài đầy đủ qua CLI gồm 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và một daemon chạy nền.
B.Swarm: nhiều agent làm chung một việc
Thay vì một agent làm tuần tự, bạn có thể yêu cầu một swarm. Ví dụ trong README là cho swarm rà soát cả repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Với người làm dự án thật, đây là kiểu việc mà chia nhỏ cho nhiều agent sẽ gọn hơn.
C.Bộ nhớ và học từ kinh nghiệm
Ruflo có bộ nhớ giữ lại giữa các phiên làm việc, và cơ chế học từ những tác vụ đã thành công để định tuyến tốt hơn lần sau. README lưu ý đây là một vòng học ở mứ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 cấu hình. Nghĩa là đừng kỳ vọng nó tự thông minh lên mà không cấu hình gì.
D.Bảng điều khiển ngay cạnh Claude Code
Plugin ruflo-console là một "buồng lái": theo dõi workflow, agent, mô hình, token và chi phí cạnh Claude Code, mở log để xem, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Bạn mở nó bằng lệnh /ruflo. Có thể cho Claude điều khiển bảng này, nhưng bạn đặt giới hạn quyền (xem phần dùng thực tế bên dưới).
E.Hệ sinh thái plugin
README liệt kê 48 plugin (cộng 3 plugin bên ngoài), chia nhóm: điều phối (swarm, autopilot, workflow, federation), bộ nhớ (agentdb, rag-memory, knowledge-graph), học tập, chất lượng mã (testgen, browser, docs, jujutsu), bảo mật (security-audit, aidefence), kiến trúc, DevOps (cost-tracker, observability) và mở rộng. Bạn chỉ cần cài thứ mình cần, ví dụ ruflo-testgen để tìm chỗ thiếu test và sinh test, hay ruflo-cost-tracker để theo dõi token và đặt ngân sách.
F.Federation và các client khác
Với federation, agent trên các máy khác nhau có thể giao tiếp an toàn. Ngoài Claude Code, Codex và các MCP client khác cũng dùng được, chỉ cần trỏ tới npx -y ruflo@latest mcp start. README còn có tùy chọn --grok 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 (theo
package.json). Bạn cần cónpxđi kèm Node. - Claude Code hoặc Codex (hay một MCP client khác) để dùng các agent.
- Nếu đi đường plugin của Claude Code: Claude Code phiên bản 2.1.287 trở lên. Lệnh cài từ terminal (
claude plugin install ...) cần bản 2.1.292 trở lên. - Tài khoản và quyền truy cập của chính công cụ AI bạn dùng (Claude Code, Codex).
README phần được cung cấp không nói gì về yêu cầu GPU, dung lượng ổ đĩa hay hệ điều hành cụ thể, nên mình không khẳng định. Phần plugin có nhắc tới các plugin tùy chọn như chạy LLM cục bộ hoặc tìm kiếm tăng tốc GPU, nhưng đó là phần thêm, không phải điều kiện để bắt đầu.
Các mod trong Ruflo chạy với quyền tài khoản của bạn và không bị đặt trong hộp cát (sandbox). README khuyên đọc mã của mod trước khi cài. Hãy thử trên một dự án không chứa dữ liệu nhạy cảm trước.
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 initGõ npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thậtDán một câu lệnh mẫu để thử swarm
- (Tùy chọn) Cài plugin hoặc bảng điều khiểnDùng /plugin để thêm console và mod
A.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 bạn đang đứng. Nếu bạn mở terminal ở sai chỗ (ví dụ thư mục người dùng), nó sẽ thêm file vào đó. Hãy cd vào dự án trước. Tên thư mục dưới đây chỉ là ví dụ:
cd ten-thu-muc-du-anTrên Windows bạn có thể dùng PowerShell hoặc Git Bash, lệnh cd giống nhau.
B.Chạy lệnh init
Đây là lệnh chính theo README:
npx ruflo@latest initnpx tải và chạy bản Ruflo mới nhất mà không cần cài toàn cục. Lệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh của README, nó tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và file settings trong thư mục làm việc. Nếu dự án của bạn đã có CLAUDE.md, hãy sao lưu hoặc dùng Git để xem khác biệt sau khi chạy.
Nếu muốn thiết lập 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 ngay trong thư mục đó. README nói Claude Code sẽ nhận các thành phần mới ở lần khởi động kế tiếp, nên nếu bạn đang mở sẵn thì hãy thoát ra và mở lại.
D.Giao một tác vụ thật
Dán câu lệnh mẫu của README vào Claude Code:
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, ý chính là yêu cầu "dùng ruflo swarm" cho việc đó.
E.Cách khác: chỉ cài plugin trong Claude Code
Nếu bạn không muốn thêm file nào vào dự án, README có đường "plugin". Cần Claude Code từ 2.1.287 trở lên. Chạ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
/rufloCác dòng này gõ trong khung chat của Claude Code, không phải trong terminal thường. Đường này không để lại file nào trong dự án. Đổi lại, README nói nó chỉ cho lệnh slash, vài skill và định nghĩa agent, không có hook. Muốn dùng đủ vòng lặp như tài liệu mô tả thì dùng init.
Từ terminal, trên Claude Code 2.1.292 trở lên:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloF.Dùng với Codex hoặc MCP client khác
Không cần thiết lập dự án: cấu hình lệnh (command) là npx với các đối số (arguments):
["-y", "ruflo@latest", "mcp", "start"]Cách điền cụ thể tùy từng client, README không hướng dẫn chi tiết cho từng phần mềm. Bạn xem tài liệu của client mình dùng để biết chỗ nhập command và arguments.
G.Chạy bảng điều khiển 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 một khung hình duy nhất, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra theo tư liệu:
- Sau
init, thư mục dự án có thêm các mục như.claude/,.claude-flow/và fileCLAUDE.md. - Mở lại Claude Code, gõ
/ruflo. Với đường cài plugin, mở/pluginvà xemruflo-console,ruflo-modscó xuất hiện trong dòng mod đang hoạt động hay không. - Thử câu lệnh swarm mẫu ở trên và xem Claude Code có điều phối agent, viết test và tóm tắt thay đổi không.
- Với bảng điều khiển, thử
npx ruflo tuiđể thấy giao diện chạy được trong terminal.
README không nêu một dòng "thành công" cố định để đối chiếu, nên tiêu chí thực tế là: lệnh init không báo lỗi, /ruflo mở được và Claude Code nhận ra công cụ mới.
V.Dùng vào việc thật
Các tình huống dưới đây bám vào những khả năng được README nêu. Kết quả cụ thể sẽ tùy dự án và mô hình bạn dùng.
A.Lập trình viên: rà soát một repo lạ
Bạn vừa nhận một repo từ đồng nghiệp và chưa biết phần nào dễ hỏng. Mở Claude Code trong repo đó (đã chạy init) và nhập:
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 theo README: swarm chỉ ra module rủi ro nhất, viết test cho nó và đưa bản tóm tắt thay đổi. Bạn đọc lại test, chạy thử và quyết định có giữ hay không. Đừng bỏ qua bước xem lại này.
Đừng học hết 406 công cụ: chạy init, rồi cứ dùng Claude Code như bình thường.
Ông T
B.Người quản lý dự án: theo dõi agent và chi phí
Bạn muốn biết agent đang làm gì và tốn bao nhiêu token. Cài ruflo-console (xem phần cài đặt), mở /ruflo để xem workflow, agent, mô hình, token và chi phí cạnh Claude Code. Muốn thêm kiểm soát ngân sách thì README có plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Bạn mở danh mục plugin bằng /ruflo market để cài, bật, tắt và cập nhật, mỗi thao tác đều hỏi xác nhận trước.
C.Người mới: để Claude tạo một "mission" trong bảng điều khiển
Đây là bài thử an toàn mà README mô tả từng bước:
- Cài console, mở
/ruflo, vào Settings → Claude control và chọn write + ask. - Nhập 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 trong console.
- Kiểm tra mục Missions có mục tiêu đó và mục Overview ghi lại hành động.
- Muốn dừng, bấm Take back control.
Hai điều cần nhớ. Một: mức mặc định hiện là read + ask, các mức quyền là read, write, manage, full, và các hành động mạng, chi tiêu hay phá hủy luôn cần xác nhận kể cả khi bạn chọn auto. Hai: tạo mission không có nghĩa tính năng đã được viết xong.
D.Dev nhóm nhỏ: sinh test và kiểm tra bảo mật bằng plugin
Bạn có một dự án lâu năm thiếu test. Cài plugin theo cách README hướng dẫn, ví dụ:
/plugin install ruflo-testgen@rufloREADME mô tả plugin này là "tìm test còn thiếu và sinh tự động". Tương tự, ruflo-security-audit quét lỗ hổng và CVE, còn ruflo-aidefence chặn prompt injection và phát hiện dữ liệu cá nhân. Hãy cài từng plugin một, thử trên nhánh riêng và đọc kỹ kết quả trước khi gộp vào nhánh chính.
VI.Lỗi hay gặp và cách xử lý
A.Chạy npx báo lỗi hoặc không chạy
Phiên bản Node quá cũ là nguyên nhân dễ gặp nhất, vì package.json yêu cầu Node 20 trở lên. Kiểm tra bằng node --version. Nếu thấp hơn 20, hãy nâng cấp Node rồi chạy lại.
B.Mở Claude Code nhưng không thấy gì mới
README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp sau init. Hãy thoát hẳn rồi mở lại, và chắc chắn bạn mở Claude Code đúng trong thư mục đã chạy init. Với đường plugin, chạy /reload-plugins.
C.Lệnh /plugin hoặc claude plugin install không hoạt động
Đường plugin cần Claude Code 2.1.287 trở lên, còn lệnh cài từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code nếu bản của bạn thấp hơn.
D.Cài một plugin hai lần, lệnh bị nạp trùng
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, hoặc marketplace gốc của chúng, hoặc ruflo. Nếu bật từ cả hai, mod và lệnh sẽ nạp hai lần. Hãy gỡ một bên.
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à là cơ chế an toàn: thao tác vượt quá mức quyền bạn đặt sẽ bị từ chối. Nếu bạn đã bấm Take back control, các lệnh sau đó cũng bị từ chối cho đến khi bạn trả quyền lại. Muốn cho phép thì nâng mức quyền một cách có chủ đích trong Settings → Claude control, và nhớ rằng thao tác mạng, chi tiêu, phá hủy vẫn cần bạn xác nhận.
VII.Có nên dùng không
Điểm mạnh. Cài đặt nhanh (một lệnh), giấy phép MIT, dự án vẫn được cập nhật trong vài tháng gần đây và có cộng đồng lớn. Bạn có thể chọn mức "nhẹ" (chỉ plugin, không file trong dự án) hoặc mức "đầy đủ" (init). Cơ chế quyền read / write / manage / full kèm ask / auto cho bạn quyền kiểm soát rõ ràng. Thêm vào đó là bảng điều khiển để nhìn thấy agent, token và chi phí.
Giới hạn. Hệ thống rất rộng: hàng chục plugin, hàng trăm công cụ. Người mới dễ choáng, nên bắt đầu từ một tác vụ nhỏ. README tự nói rõ một số thứ chỉ là minh họa: hoạt ảnh workflow dùng dữ liệu mẫu, và vòng học là mô hình khái niệm, không phải bằng chứng cho mọi kết quả. Phần README mình có cũng chưa nói về hiệu quả đo được so với dùng Claude Code đơn thuần, nên mình không khẳng định nó luôn làm nhanh hơn hay rẻ hơn. Nhiều agent chạy song song còn có thể tốn token hơn, vì vậy hãy theo dõi chi phí.
Khi nên chọn cách khác. Nếu việc của bạn là sửa vài file nhỏ, một phiên Claude Code thường là đủ và đơn giản hơn. Nếu bạn không muốn thêm file như .claude/ và CLAUDE.md vào dự án, hãy dùng đường plugin hoặc chỉ chạy MCP server. Nếu dữ liệu rất nhạy cảm, hãy đọc kỹ mã của mod và cấu hình quyền trước khi dùng, vì mod chạy với quyền tài khoản của bạn.
Câu hỏi thường gặp
Ruflo có miễn phí không?
Mã nguồn dùng giấy phép MIT nên dùng, sửa và phân phối được. Tuy nhiên Ruflo chạy trên Claude Code, Codex hoặc nhà cung cấp mô hình khác, và chi phí token của các dịch vụ đó vẫn do bạn chịu. Tư liệu không nêu mức giá cụ thể.
Ruflo khác gì dùng Claude Code thuần?
Claude Code là công cụ để mô hình làm việc, còn Ruflo là lớp harness bọc quanh nó. Ruflo thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên, hook, MCP server và bảng điều khiển. Tư liệu chưa có số liệu so sánh hiệu quả giữa hai cách.
Cần cài gì trước khi dùng Ruflo?
Bạn cần Node.js từ 20.0.0 trở lên để chạy `npx`. Nếu cài qua plugin thì cần Claude Code từ 2.1.287 trở lên (lệnh `claude plugin install` cần 2.1.292 trở lên). Tư liệu không nêu yêu cầu GPU.
Dùng được với Codex hoặc công cụ khác ngoài Claude Code 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ới arguments `["-y", "ruflo@latest", "mcp", "start"]`. Cách điền chi tiết phụ thuộc vào từng phần mềm client.
Có chạy được trên Windows không?
Tư liệu mình có không nêu rõ hệ điều hành được hỗ trợ. Ruflo chạy qua Node và `npx`, nên nếu máy bạn có Node 20 trở lên thì có thể thử, nhưng mình không thể khẳng định mọi tính năng đều chạy tốt trên Windows.
Ruflo có ghi file vào dự án của tôi không?
Có nếu dùng `npx ruflo@latest init`: nó thêm các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings. Nếu không muốn, hãy dùng đường cài plugin, README ghi là không thêm file nào vào dự án.
Có an toàn khi cho Claude điều khiển bảng điều khiển không?
README cho bạn đặt mức quyền (read, write, manage, full) và chế độ ask hoặc auto, mặc định là read + ask. Hành động mạng, chi tiêu và phá hủy vẫn cần xác nhận kể cả khi ở chế độ auto, và 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.


