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, bộ nhớ và các hook tự động. Cài bằng một lệnh npx trong thư mục dự án, cần Node từ 20 trở lên, người mới làm được trong vài phút.
ruflo là một "agent harness" mã nguồn mở: lớp công cụ đặt quanh Claude Code và Codex để các AI agent không chỉ chạy đơn lẻ mà biết phối hợp, nhớ việc cũ và tuân theo giới hạn bạn đặt. Tác giả mô tả ngắn gọn: model viết, còn harness cấp công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát để model làm việc thật. Repo trước đây tên Claude Flow và do Reuven Cohen (rUv) xây dựng.
Nếu bạn đã dùng Claude Code và thấy mỗi phiên làm việc lại bắt đầu từ con số không, hoặc muốn giao một việc lớn cho nhiều agent cùng làm, ruflo nhắm đúng chỗ đó. Người dùng hợp nhất là lập trình viên đã quen Claude Code. Dân văn phòng hoặc chủ shop vẫn dùng được nếu có người hỗ trợ cài lần đầu, vì sau khi cài bạn gần như chỉ cần dùng Claude Code như bình thường.
Điểm đáng giá nhất là mức độ dễ vào: một lệnh npx ruflo@latest init trong thư mục dự án là xong phần cài. Repo hiện có khoảng 81.600 sao và khoảng 9.600 fork, giấy phép MIT, viết chủ yếu bằng TypeScript và vẫn được cập nhật trong vài tháng gần đây.
ruvnet/ruflo
ruflo là lớp điều phối (harness) bọc quanh Claude Code và Codex: thêm agent chuyên biệt, bộ nhớ qua nhiều phiên, hook và MCP server chỉ với một lệnh init.
I.ruflo làm được gì
README giới thiệu rất nhiều thứ, nhưng chính tác giả cũng khuyên người mới đừng cố học hết. Bạn không cần thuộc 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ư thường, các hook sẽ tự định tuyến tác vụ và phối hợp agent ở phía sau. Dưới đây là những phần đáng biết nhất.
- Agent chuyên biệt và swarm. Thay vì một AI làm mọi thứ, ruflo cho nhiều agent chia việc như một nhóm nhỏ. Lợi ích: một yêu cầu lớn như "rà soát cả repo" được chia nhỏ và xử lý song song.
- Bộ nhớ qua nhiều phiên. Agent có thể lưu và truy lại kinh nghiệm từ các lần làm trước, kể cả dùng tìm kiếm vector. Bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code.
- Hook tự động. Hook định tuyến tác vụ và rút kinh nghiệm từ những lần làm thành công, chạy ngầm mà bạn không phải gõ thêm gì.
- Bảng điều khiển (console). Cho bạn xem workflow, agent, model, token và chi phí ngay cạnh Claude Code. Bạn có thể mở log của từng agent, tìm kiếm, xem lại lỗi.
- Quyền điều khiển có giới hạn. Trong phần Settings, mục Claude control cho phép Claude thao tác trên console theo bốn mức:
read,write,manage,full, với chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận, kể cả khi đểauto. - Hệ plugin. Có 48 plugin trong marketplace, chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps, mở rộng. 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-security-auditquét lỗ hổng. - Federation. Cho phép agent trên các máy khác nhau phối hợp với nhau. Đây là tính năng nâng cao, người mới chưa cần đụng tới.
- Dùng được ngoài Claude Code. Codex và các client MCP khác kết nối được; ngoài ra có chế độ terminal UI chạy độc lập.
II.Cần chuẩn bị gì
Tư liệu cho biết những điều sau:
- Node.js từ 20.0.0 trở lên.
package.jsoncủa repo yêu cầu như vậy. Các lệnh trong hướng dẫn đều dùngnpx, đi kèm Node. - Claude Code, nếu bạn đi đường plugin: cần phiên bản 2.1.287 trở lên. Riêng lệnh cài plugin từ terminal cần Claude Code 2.1.292 trở lên.
- Codex hoặc client MCP khác nếu bạn không dùng Claude Code.
- Repo có file
SKILL.mdvà thư mục.claude-plugin, nên cũng nằm trong hệ sinh thái skill/plugin của Claude Code.
Về hệ điều hành, tài khoản AI cụ thể, API key hay phần cứng (GPU, RAM), phần README mình đọc được chưa nói rõ. Nếu bạn cần chắc chắn, hãy xem thêm thư mục docs/ trong repo. Bạn cũng sẽ cần có sẵn quyền dùng Claude Code hoặc Codex, vì ruflo là lớp bọc bên ngoài chứ không thay chúng.
Mods của ruflo chạy với quyền của tài khoản bạn và không được đặt trong sandbox. README khuyên đọc code trước khi cài. Hãy giữ Claude control ở mức mặc định read + ask cho đến khi bạn quen.
III.Cài đặt từng bước
README đưa ra vài đường cài. Đường chính là npx ruflo@latest init trong thư mục dự án. Đường nhẹ hơn là cài plugin trong Claude Code, không thêm file nào vào dự án.
- Mở terminal đúng thư mụcVào thư mục dự án mà bạn muốn dùng ruflo
- Chạy initChạy npx ruflo@latest init để thêm agent, hook, 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
- Giao một việc thậtGõ yêu cầu dùng swarm của ruflo
- (Tuỳ chọn) Cài consoleCài plugin ruflo-console rồi gõ /ruflo
A.Mở terminal đúng thư mục
Lỗi người mới hay gặp nhất là chạy lệnh sai chỗ. init thêm 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ủa mình. Ví dụ, nếu dự án nằm trên máy bạn thì làm như sau (thay đường dẫn cho đúng):
cd duong-dan-toi-du-an-cua-banB.Chạy lệnh init
Đây là lệnh chính theo README:
npx ruflo@latest initnpx tải và chạy ruflo mà không cần cài toàn cục. Theo README, init thêm agent, hook, bộ nhớ và MCP server vào dự án. Bảng so sánh trong README cho biết đường CLI này tạo ra .claude/, .claude-flow/, CLAUDE.md, các file helper và 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 để so sánh trước khi chạy.
Nếu muốn thiết lập theo kiểu hỏi đáp từng bước, README có thêm lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code
Claude Code nhận cấu hình mới ở lần khởi động kế tiếp. Vì vậy hãy thoát Claude Code nếu nó đang mở, rồi mở lại trong cùng thư mục dự án.
D.Cách khác: chỉ cài plugin trong Claude Code
Đường 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õ các lệnh sau 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
/rufloMấy dòng này lần lượt thêm kho plugin của ruflo, cài ba plugin (lõi, console, mods), nạp lại plugin rồi mở console. Bạn cũng có thể cài từ terminal, với Claude Code 2.1.292 trở lên:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloLưu ý README nói rõ: bản plugin là bản "lite", chủ yếu thêm lệnh slash và định nghĩa agent. Muốn có đủ vòng lặp (98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon) thì dùng đường npx ruflo@latest init.
E.Dùng với Codex hoặc client MCP khác
Cấu hình client của bạn với command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Cách điền cụ thể tuỳ từng client; README chỉ nói bạn trỏ client tới lệnh npx -y ruflo@latest mcp start.
F.Chạy giao diện terminal riêng
Console có thể chạy độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain nếu muốn in ra một khung hình để dùng trong script.
IV.Kiểm tra đã chạy được chưa
Theo README, dấu hiệu chạy được gồm:
- Lệnh
npx ruflo@latest initchạy xong và trong thư mục dự án xuất hiện các mục như.claude/,.claude-flow/vàCLAUDE.md(bảng so sánh của README liệt kê những mục này cho đường CLI). - Sau khi mở lại Claude Code, gõ
/ruflothì console hiện ra (với đường plugin hoặc khi đã cài console). - Nếu cài bằng plugin, mở
/pluginvà kiểm tra các mod có trong dòng "active mods". - Gõ
/ruflo markettrong console để mở Plugin Catalog, nơi liệt kê plugin, mod và skill kèm nút cài, bật, tắt và cập nhật (mỗi thao tác đều hỏi lại trước).
Cách kiểm tra chắc nhất là giao một việc nhỏ và xem Claude Code có phối hợp agent không, như ở phần dưới.
V.Dùng vào việc thật
A.Rà soát một repo cũ và viết test cho phần rủi ro nhất
Bối cảnh: bạn là lập trình viên mới nhận một dự án chưa ai viết test. Sau khi init và mở lại Claude Code, bạn gõ đú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 Code chia việc cho nhiều agent, chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Hãy đọc lại phần tóm tắt và xem diff trước khi giữ lại.
Model viết code, còn harness lo phần còn lại: công cụ, trí nhớ và giới hạn.
Ông T
B.Theo dõi chi phí và tiến độ ngay cạnh Claude Code
Bối cảnh: bạn chạy nhiều tác vụ dài và lo tốn token. Cài ruflo-console, mở /ruflo để xem workflow, agent, model, token và chi phí. Muốn có cảnh báo ngân sách, README liệt kê plugin ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Kết quả là bạn thấy việc nào đang tốn nhiều mà không phải đoán.
C.Cho Claude tạo "mission" nhưng bạn giữ quyền duyệt
Bối cảnh: bạn muốn thử cho Claude điều khiển console mà vẫn an toàn. Làm theo các bước trong README:
- Mở
/ruflo, vào Settings → Claude control, chọn write + ask. - Gõ yêu cầu cụ thể, ví dụ: "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 thao tác tạo đang chờ.
- Kiểm tra mục Missions và Overview có ghi lại hành động.
README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được làm xong. Nếu cần dừng, bấm Take back control.
D.Thử một plugin lẻ mà không đụng vào dự án
Bối cảnh: bạn chỉ muốn thử sinh test hoặc quản lý tài liệu mà chưa muốn thêm file vào repo. Dùng đường plugin (Path A trong README): thêm marketplace rồi cài đúng plugin cần, ví dụ:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@rufloKết quả: bạn có thêm lệnh slash và định nghĩa agent mà không có file mới trong dự án. Đổi lại, bạn không có đủ hook và daemon như đường init.
VI.Lỗi hay gặp và cách xử lý
Một số lỗi dưới đây là những chỗ rất dễ vấp với loại công cụ này. README chưa có mục xử lý sự cố riêng, nên đây là hướng dẫn chung, an toàn.
- Lệnh
npxbáo không tìm thấy hoặc lỗi phiên bản Node. Repo yêu cầu Node từ 20.0.0. Gõnode --versionđể kiểm tra, nếu thấp hơn thì cập nhật Node rồi chạy lại. - Gõ
/ruflohoặc/pluginmà không nhận lệnh. Plugin yêu cầu Claude Code từ 2.1.287 trở lên. Hãy cập nhật Claude Code, sau đó chạy/reload-pluginshoặc mở lại phiên. - Chạy
initxong mà Claude Code không thấy agent mới. Claude Code chỉ nhận cấu hình ở lần khởi động kế tiếp. Thoát hẳn rồi mở lại trong đúng thư mục bạn đã chạyinit. - Cài cùng một plugin từ hai kho. README cảnh báo với các plugin 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 hai lần. Nếu đã lỡ cài hai nơi, hãy gỡ một bản. - Claude làm thao tác bị từ chối. Có thể mức quyền Claude control đang thấp. Mặc định là read + ask; muốn cho phép ghi thì tự nâng lên, nhưng nên giữ chế độ
askđể còn duyệt từng thao tác.
VII.Có nên dùng không
Điểm mạnh: cài rất gọn bằng một lệnh, giấy phép MIT, dự án hoạt động và có cộng đồng lớn. Các lớp kiểm soát (quyền theo mức, xác nhận trước thao tác nhạy cảm, nút lấy lại quyền) cho thấy tác giả có nghĩ đến an toàn. README cũng khá trung thực: nói rõ bản demo dùng dữ liệu mẫu, không chứng minh swarm hay bộ nhớ làm xong việc thật.
Giới hạn: phạm vi rất rộng nên người mới dễ choáng. Đường init thêm khá nhiều file vào dự án. Mods không chạy trong sandbox. Phần mô tả về học và bộ nhớ trong README được tác giả gọi là luồng khái niệm, và cần embedding cùng các module cấu hình mới chạy đầy đủ. Về chi phí và yêu cầu phần cứng cụ thể, README chưa nói rõ.
Khi nào 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ỏ, bản thân Claude Code là đủ. Nếu chỉ muốn thử một vài lệnh, hãy bắt đầu bằng đường plugin nhẹ. Nếu bạn làm việc với dữ liệu nhạy cảm, hãy đọc SECURITY.md trong repo trước khi bật các tính năng liên quan mạng hay federation.
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 tự do. Tuy nhiên ruflo bọc quanh Claude Code và Codex, nên chi phí dùng các dịch vụ đó vẫn theo gói của bạn. README có plugin theo dõi token và ngân sách, còn chi tiết giá thì chưa có thông tin.
Có chạy được trên Windows không?
Phần README mình đọc được chưa nói rõ về hệ điều hành. Yêu cầu được nêu là Node.js 20 trở lên và các lệnh đều dùng `npx`. Bạn nên xem thư mục `docs/` của repo hoặc thử chạy để chắc chắn.
Có cần GPU không?
Tư liệu không nêu yêu cầu GPU cho đường cài cơ bản. Có một plugin nhắc tới tìm kiếm tăng tốc GPU, nhưng đó là tuỳ chọn riêng. Chưa có thông tin về cấu hình phần cứng tối thiểu.
Cài ruflo có làm thay đổi dự án của tôi không?
Có, nếu dùng `npx ruflo@latest init`: lệnh này tạo các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md` và file settings. Nếu muốn không thêm file nào, hãy dùng đường cài plugin trong Claude Code, theo README thì đường này không để lại file trong dự án.
ruflo khác gì dùng Claude Code thuần?
Claude Code là agent làm việc chính, còn ruflo là lớp bọc thêm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook và console theo dõi. Sau khi cài, bạn vẫn dùng Claude Code như bình thường, phần phối hợp chạy ngầm.
Dữ liệu của tôi có an toàn không?
README nêu các lớp kiểm soát như mức quyền read/write/manage/full và yêu cầu xác nhận với thao tác mạng, chi tiêu, phá huỷ. Đồng thời nó cảnh báo mods chạy với quyền tài khoản bạn và không có sandbox. Hãy đọc code và `SECURITY.md` trước khi dùng với dữ liệu nhạy cảm.
Dùng với Codex hoặc client MCP khác được không?
Được. README hướng dẫn cấu hình client với command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`. Cách điền cụ thể phụ thuộc từng client nên bạn cần xem tài liệu của client đó.


