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 "harness" bọc quanh Claude Code và Codex, thêm đội agent, bộ nhớ lưu giữa các phiên, hook và MCP server. Bạn cài bằng một lệnh npx trong thư mục dự án, cần Node 20 trở lên. Cài không khó, nhưng bộ công cụ rất rộng nên nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một "agent harness", tức lớp điều phối đặt quanh Claude Code và Codex. Model chỉ viết code, còn Ruflo cung cấp phần còn lại: nhiều agent chuyên biệt, bộ nhớ giữ lại giữa các lần làm việc, hook tự động và một MCP server để các agent phối hợp với nhau. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.600 sao và khoảng 9.600 fork trên GitHub, giấy phép MIT.
Vấn đề nó giải quyết khá quen thuộc. Dùng Claude Code một mình thì mỗi phiên làm việc khá đơn lẻ: tác vụ lớn phải bạn tự chia nhỏ, và kinh nghiệm của lần trước không tự mang sang lần sau. Ruflo thêm vào dự án của bạn một đội agent, một bộ nhớ và các quy tắc định tuyến công việc. Theo README, sau khi chạy init bạn cứ dùng Claude Code bình thường, phần định tuyến và phối hợp chạy ngầm.
Nếu bạn là lập trình viên mới, người làm kỹ thuật ở công ty nhỏ, hoặc người đã quen Claude Code và muốn giao những việc dài hơn (xem xét cả repo, viết test, theo dõi chi phí), repo này đáng thử. Điểm đáng giá nhất là cách cài rất ngắn: một lệnh npx, và có thêm đường cài kiểu plugin không để lại file nào trong dự án.
ruvnet/ruflo
Ruflo là lớp điều phối bọc quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server cho dự án chỉ bằng một lệnh npx.
I.Ruflo làm được gì
Ruflo có rất nhiều thứ. README nói bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Dưới đây là những phần dễ thấy lợi ích nhất.
- Đội agent chuyên biệt (swarm). Bản cài bằng CLI đi kèm khoảng 98 agent, hơn 60 lệnh và 30 skill. Bạn giao một việc lớn, các agent chia nhau làm thay vì một phiên Claude phải ôm hết.
- Bộ nhớ giữa các phiên. Agent nhớ lại thứ đã làm trước đó. Các plugin như
ruflo-agentdb,ruflo-rag-memory,ruflo-rvflo việc lưu, tìm kiếm và khôi phục bộ nhớ. Ích lợi thực tế: lần sau bạn không phải giải thích lại bối cảnh dự án từ đầu. - Hook tự động. Hook định tuyến tác vụ và ghi nhận mẫu làm việc thành công, chạy nền, bạn không phải gõ thêm lệnh.
- Bảng điều khiển (console). Một "buồng lái" cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí. Bạn mở nó bằng lệnh
/ruflo. Có thể xem log từng lần chạy, tìm kiếm, phân loại lỗi, phát lại và so sánh. - Cho Claude lái console nhưng bạn đặt giới hạn. Trong phần Settings có mục Claude control với bốn mức
read,write,manage,fullvà hai chế độ duyệtaskhoặcauto. Mặc định hiện là read + ask. Hành động liên quan mạng, chi tiền hoặc xoá vẫn phải xác nhận, kể cả khi đểauto. - Kho plugin lớn. Có 48 plugin chia theo nhóm: điều phối, bộ nhớ, học tập, kiểm thử, bảo mật, DevOps, v.v. Ví dụ
ruflo-testgentìm test còn thiếu và sinh test,ruflo-cost-trackertheo dõi token và đặt ngân sách,ruflo-aidefencechặn prompt injection và dò thông tin cá nhân. - Federation. Agent trên các máy khác nhau có thể phối hợp với nhau (plugin
ruflo-federation). Phần này dành cho nhu cầu nâng cao. - Dùng được ngoài Claude Code. Codex và các MCP client khác trỏ được vào Ruflo. README cũng có lệnh
npx ruflo tuiđể chạy console ngay trong terminal.
II.Cần chuẩn bị gì
Tư liệu của repo chỉ nêu những thứ sau:
- Node.js 20.0.0 trở lên (theo
package.json). Lệnh cài dùngnpx, đi kèm Node. - Claude Code, nếu bạn dùng đường cài plugin: cần bản 2.1.287 trở lên. Lệnh
claude plugin installở terminal cần bản 2.1.292 trở lên. - Một thư mục dự án để chạy
init(đường cài bằng CLI sẽ thêm file vào đó). - Hoặc Codex / một MCP client khác nếu bạn không dùng Claude Code.
README phần đã cung cấp không nói gì về hệ điều hành cụ thể, yêu cầu GPU hay dung lượng ổ đĩa, nên mình không khẳng định. Về tài khoản và key: bạn vẫn cần tài khoản để dùng Claude Code hoặc Codex như bình thường. README không đòi thêm một API key riêng nào cho bước cài ban đầu.
Các "mod" của Ruflo chạy với quyền tài khoản của bạn và không bị đưa vào sandbox. README khuyên đọc code của mod trước khi cài. Hãy làm vậy, đừng bấm cài theo thói quen.
III.Cài đặt từng bước
README đưa ra ba đường: cài bằng CLI (đầy đủ nhất), cài plugin trong Claude Code (nhẹ, không thêm file), và cài cho Codex hoặc MCP client khác. Mình hướng dẫn đường đầu tiên làm chính, hai đường còn lại làm lựa chọn.
- Kiểm tra NodeChắc chắn máy có Node 20 trở lên
- Mở terminal trong dự ánĐứng đúng thư mục bạn muốn thêm Ruflo vào
- Chạy initThêm agent, hook, bộ nhớ và MCP server vào dự án
- Mở lại Claude CodeKhởi động Claude Code ở cùng thư mục để nó nhận cấu hình
- Mở consoleGõ /ruflo để xem bảng điều khiển
A.Kiểm tra Node
Ruflo cần Node 20 trở lên. Mở terminal (PowerShell trên Windows, Terminal trên macOS) và xem phiên bản:
node --versionNếu số hiện ra nhỏ hơn 20, bạn cần nâng cấp Node trước. README không hướng dẫn việc này, bạn xem trang chủ Node.js.
B.Mở terminal trong thư mục dự án
Đây là chỗ người mới hay vấp. Lệnh init ghi file vào thư mục hiện hành, nên bạn phải cd vào đúng dự án trước. Đường dẫn dưới đây chỉ là ví dụ, bạn thay bằng thư mục của mình:
cd duong-dan-toi-du-an-cua-banC.Chạy init
Đây là lệnh chính theo README:
npx ruflo@latest initnpx tải Ruflo bản mới nhất rồi chạy luôn, 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 README, bạn sẽ thấy các thư mục và file như .claude/, .claude-flow/, CLAUDE.md xuất hiện trong dự án. Nếu bạn muốn được hỏi từng bước, README có lệnh thiết lập tương tác:
npx ruflo@latest init wizardD.Mở lại Claude Code và gõ /ruflo
Claude Code chỉ nhận cấu hình mới ở lần khởi động tiếp theo. Vì vậy hãy thoát và mở lại Claude Code trong cùng thư mục. Sau đó gõ lệnh sau trong Claude Code để mở console:
/rufloE.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õ từng dòng sau ngay 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
/rufloNếu bạn dùng Claude Code 2.1.292 trở lên, có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloNhớ rằng đường plugin nhẹ hơn: README so sánh là nó không cài hook, và chỉ đăng ký MCP server nếu có ruflo-core. Muốn trọn vẹn "vòng lặp Ruflo" như tài liệu mô tả thì dùng đường CLI.
F.Cách khác: Codex hoặc MCP client khác
Cấu hình client của bạn với command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]Tương đương dòng lệnh là:
npx -y ruflo@latest mcp startMỗi client lưu cấu hình ở chỗ khác nhau. README phần mình có không chỉ file cấu hình của từng client, nên bạn xem tài liệu của client đó.
G.Muốn chạy trong terminal thuần
Console chạy được độc lập, không cần Claude Code:
npx ruflo tuiThêm --plain để in ra một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
Với đường cài bằng CLI:
- Sau
npx ruflo@latest init, nhìn trong thư mục dự án xem đã có.claude/,.claude-flow/vàCLAUDE.mdchưa. - Mở lại Claude Code ở cùng thư mục, gõ
/ruflo. Console hiện ra là dấu hiệu tốt nhất.
Với đường plugin: gõ /plugin và xem các plugin bạn vừa cài có xuất hiện ở dòng "active mods" không, rồi gõ /ruflo. Trong console, /ruflo market mở Plugin Catalog, liệt kê plugin, mod và skill kèm nút cài, bật, tắt, cập nhật (mỗi thao tác đều hỏi lại trước khi làm).
Nếu /ruflo không nhận, xem phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
Các tình huống dưới đây bám đúng ví dụ và khả năng README mô tả. Kết quả thực tế phụ thuộc dự án và model bạn dùng.
A.Nhờ đội agent rà soát cả repo
Bối cảnh: bạn là lập trình viên nhận lại một dự án cũ, không biết chỗ nào dễ hỏng. Sau khi cài và mở lại Claude Code, bạn đưa đúng câu 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: đội agent tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn nên đọc lại phần tóm tắt và chạy test trước khi giữ thay đổi.
Model viết code, còn Ruflo lo công cụ, bộ nhớ, vòng lặp và giới hạn để agent làm việc được thật.
Ông T
B.Giao Claude tạo một "mission" trong console
Bối cảnh: bạn là chủ sản phẩm muốn thử xem Claude điều khiển console an toàn ra sao. README hướng dẫn:
- Mở
/ruflo, vào Settings, chọn Claude control, đặt write + ask. - Nhập yêu cầu cụ thể:
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.
Lưu ý của README: tạo mission không có nghĩa tính năng đã được làm xong. Muốn dừng, bấm Take back control, và các lời gọi sau đó sẽ bị từ chối cho đến khi bạn trả quyền lại.
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 thay vì Claude Code. Bạn không cần đổi công cụ, chỉ cấu hình MCP client với command npx và đối số -y ruflo@latest mcp start như phần cài đặt ở trên. Muốn thiết lập theo dự án, chạy npx ruflo@latest init wizard. Kết quả là Codex gọi được các công cụ MCP của Ruflo.
D.Theo dõi chi phí và sinh test bằng plugin riêng lẻ
Bối cảnh: bạn không muốn cài cả bộ, chỉ cần vài việc. Cài từng plugin theo cách ở trên. Theo bảng plugin trong README, ruflo-testgen tìm test còn thiếu và sinh tự động, còn ruflo-cost-tracker theo dõi lượng token, đặt ngân sách và cảnh báo chi phí. README không đưa ví dụ lệnh cụ thể cho hai plugin này, nên sau khi cài, bạn mở /ruflo market hoặc /plugin để xem lệnh mà từng plugin cung cấp.
VI.Lỗi hay gặp và cách xử lý
README phần mình có không liệt kê mục xử lý lỗi, nên các mục dưới đây dựa trên yêu cầu và cảnh báo mà tài liệu nêu, cộng với kinh nghiệm chung với loại công cụ này.
npxbáo lỗi hoặc chạy sai khi Node cũ.package.jsonyêu cầu Node từ 20 trở lên. Chạynode --version, nâng cấp Node nếu cần rồi chạy lạinpx ruflo@latest init.- Gõ
/ruflomà không thấy gì. Với đường CLI, thoát hẳn và mở lại Claude Code ở đúng thư mục đã chạyinit. Với đường plugin, gõ/reload-plugins, rồi mở/pluginxem plugin đã bật chưa. Kiểm tra thêm phiên bản Claude Code có từ 2.1.287 trở lên không. - Plugin nạp hai lần. README cảnh báo với các plugin ngoài như
agentdb,agentic-flow,agentic-qe-fleet: nếu bật từ hai kho khác nhau, mod và lệnh sẽ nạp đôi. Hãy cài từ một kho duy nhất. - Claude từ chối thao tác trong console. Đó là cơ chế giới hạn quyền, không phải lỗi. Mức mặc định là read + ask, nên muốn tạo mission bạn phải nâng lên write. Chỉ nâng mức khi bạn chắc về việc mình đang làm.
- Gọi nhầm tên công cụ MCP. Plugin
ruflo-coređăng ký công cụ với tên dạngmcp__plugin_ruflo-core_ruflo__memory_store, khác tên ngắn nhưmemory_storecủa đường CLI. Hai đường cài đặt không dùng chung tên, nên đừng trộn tài liệu của đường này sang đường kia.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Có hai đường cài để bạn chọn mức dấn thân: đầy đủ hoặc chỉ plugin. Có console để nhìn thấy agent đang làm gì, tốn bao nhiêu token. Cơ chế phân quyền cho Claude khá rõ ràng. Giấy phép MIT và repo vẫn được cập nhật trong 3 tháng gần đây.
Giới hạn. Bộ công cụ rất rộng (48 plugin, hàng trăm công cụ MCP), người mới dễ choáng. README tự ghi rõ các đoạn demo dùng dữ liệu mẫu và không chứng minh được việc swarm hoàn thành công việc thật hay bộ nhớ gợi lại đúng. Phần "tự học" được mô tả là mô hình khái niệm, và README nói vẫn cần embedding cùng các module học được cấu hình. Đường cài bằng CLI thêm nhiều file vào dự án, nên hãy thử trên dự án có git để xem và hoàn tác thay đổi được.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code làm vài việc đơn giản, cài thêm cả một harness là thừa. Cứ dùng Claude Code trơn. Nếu bạn muốn thử nhẹ, hãy bắt đầu bằng đường plugin, chỉ ruflo-core và ruflo-console, rồi thêm dần khi thấy cầ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 bạn dùng tự do. Tuy vậy, khi agent gọi Claude Code hoặc Codex thì chi phí model vẫn theo tài khoản của bạn ở các dịch vụ đó. README có plugin `ruflo-cost-tracker` để theo dõi token và đặt ngân sách.
Cần GPU không?
Tư liệu mình có không nêu yêu cầu GPU cho việc cài và chạy cơ bản. Một số plugin như `ruflo-ruvector` được mô tả có tìm kiếm tăng tốc GPU, nhưng README không nói đó là bắt buộc.
Chạy được trên Windows không?
README phần mình có không nêu rõ hệ điều hành nào được hỗ trợ. Điều kiện duy nhất được ghi là Node 20 trở lên và Claude Code đủ phiên bản nếu dùng plugin. Bạn nên thử trên dự án nhỏ trước.
Ruflo khác gì dùng Claude Code trơn?
Claude Code trơn là một phiên làm việc đơn lẻ. Ruflo bọc thêm đội agent, bộ nhớ giữa các phiên, hook tự định tuyến và MCP server. Đổi lại, dự án của bạn có thêm nhiều file và cấu hình khi chạy `init`.
Cài plugin và chạy `npx ruflo init` khác nhau thế nào?
Plugin nhẹ hơn: không thêm file vào dự án, không cài hook, chỉ có slash command, vài skill và định nghĩa agent. Đường `init` cho vòng lặp đầy đủ gồm khoảng 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon. README khuyên đường `init` cho dùng nghiêm túc.
Dữ liệu và quyền truy cập có an toàn không?
README cho biết mod chạy với quyền tài khoản của bạn và không được sandbox, nên cần đọc code trước khi cài. Với console, mặc định Claude chỉ có quyền đọc và phải xin phép; hành động qua mạng, tốn tiền hoặc phá huỷ vẫn cần xác nhận kể cả ở chế độ auto. Về nơi lưu dữ liệu chi tiết thì tư liệu mình có chưa nói.
Dùng với Codex được không?
Được. README nói Codex và các MCP client khác chạy được: cấu hình command là `npx` với đối số `-y`, `ruflo@latest`, `mcp`, `start`. Muốn thiết lập theo dự án thì chạy `npx ruflo@latest init wizard`.


