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ở viết bằng TypeScript. Nó thêm đội agent, bộ nhớ lâu dài, hook và MCP server vào Claude Code hoặc Codex để các agent phối hợp làm việc. Cài chỉ cần một lệnh npx init trong thư mục dự án, nhưng cần Node 20 trở lên.
Ruflo là một "agent harness": lớp công cụ bọc quanh Claude Code và Codex, giúp mô hình AI không chỉ trả lời từng câu mà còn có đội agent, bộ nhớ, vòng lặp và các lớp kiểm soát để làm việc thật. Nói đơn giản, mô hình lo phần viết, còn Ruflo lo phần tổ chức: ai làm gì, nhớ gì giữa các phiên, kiểm tra kết quả ra sao.
Repo này dành cho lập trình viên đang dùng Claude Code hoặc Codex và muốn giao những việc lớn hơn một câu lệnh, ví dụ rà soát cả repo, viết test, tóm tắt thay đổi. Người làm kinh doanh hoặc văn phòng cũng có thể dùng thử, nhưng bạn cần quen mở terminal và có sẵn Claude Code. Repo hiện có khoảng 81.588 sao và 9.608 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.
Điểm đáng giá nhất là cách vào cửa rất gọn. Một lệnh npx ruflo@latest init trong thư mục dự án là xong phần cài. Sau đó bạn cứ dùng Claude Code như bình thường, README nói hệ thống hook sẽ tự định tuyến tác vụ, học từ những lần làm tốt và điều phối agent ở phía sau.
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 vào dự án chỉ với một lệnh npx.
I.Ruflo làm được gì
Trước khi vào chi tiết, bạn nên biết là README rất dài và liệt kê hàng trăm công cụ. Nhưng chính README cũng nhắn người mớ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ễ hiểu và dễ dùng nhất.
A.Đội agent phối hợp (swarm)
Ruflo thêm các agent chuyên biệt và cho chúng làm việc theo nhóm. Ở đường cài đầy đủ, README ghi 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế là bạn có thể mô tả một việc lớn, ví dụ "tìm module rủi ro nhất, viết test cho nó", và để nhiều agent chia nhau làm thay vì tự chia việc từng bước.
B.Bộ nhớ qua nhiều phiên
Phần mô tả nói Ruflo có bộ nhớ thích nghi, tìm kiếm vector và tích hợp RAG. Với người dùng, điều này nghĩa là agent có thể nhớ kinh nghiệm từ các lần làm trước thay vì bắt đầu từ con số không mỗi lần mở phiên mới. README cũng nói rõ phần học này là mô hình khái niệm, và một số phần cần embedding cùng module học được cấu hình.
C.Bảng điều khiển (console) trong Claude Code
Plugin ruflo-console cho bạn một "buồng lái" cạnh Claude Code: theo dõi workflow, agent, mô hình, token và chi phí. Bạn mở nó bằng lệnh /ruflo. Bạn cũng có thể xem log, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy.
D.Cho Claude điều khiển nhưng bạn đặt giới hạn
Trong phần Settings của console có mục "Claude control". Bạn chọn mức quyền read, write, manage hoặc full, và chế độ duyệt ask hoặc auto. README nói mặc định hiện tại là read + ask. Những hành động liên quan mạng, chi tiêu hoặc phá hủy vẫn phải xác nhận kể cả khi để auto. Có nút "Take back control" để dừng ngay.
E.Hệ plugin lớn
README liệt kê 48 plugin (cộng 3 plugin bên ngoài), chia theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), học (intelligence, goals), chất lượng code (testgen, browser, docs), bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker)… Bạn chỉ cài cái mình cần.
F.Dùng được với Codex và client MCP khác
Ngoài Claude Code, README nói Codex và các client MCP khác cũng dùng được bằng cách trỏ tới npx -y ruflo@latest mcp start. Ngoài ra README có nhắc tùy chọn --grok cho Grok Build, nhưng bài này không đi sâu phần đó.
II.Cần chuẩn bị gì
Tư liệu của repo nói khá ít về phần chuẩn bị, nên mình chỉ ghi những gì có:
- Node.js từ phiên bản 20.0.0 trở lên (package.json yêu cầu
>=20.0.0). 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. Đường cài chỉ bằng plugin cần Claude Code 2.1.287 trở lên. Lệnh cài từ terminal (
claude plugin install ...) cần 2.1.292 trở lên. - Một thư mục dự án để chạy
init. - Nếu muốn dùng Codex hoặc client MCP khác, bạn cần client đó đã có sẵn.
README phần đã cung cấp không nói yêu cầu về hệ điều hành, GPU hay dung lượng ổ đĩa, nên mình không khẳng định gì ở các mục này. Về API key hay tài khoản, README chưa nêu bước nào bắt buộc để chạy init. Tuy nhiên bản thân Claude Code hoặc Codex vẫn cần tài khoản của bạn như bình thường.
Các "mod" của Ruflo chạy với quyền tài khoản của bạn và không nằm trong sandbox. README khuyên đọc code trước khi cài. Nếu mới thử, hãy bắt đầu với quyền console ở mức read + ask.
III.Cài đặt từng bước
Ruflo có ba đường cài. Bài này đi đường chính (CLI init) trước, rồi nêu hai đường còn lại.
- Mở terminalVào đúng thư mục dự án của bạn
- Chạy initDùng npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Khởi động lại Claude CodeMở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao việc thậtGõ một yêu cầu dùng swarm của ruflo
- Mở consoleDùng /ruflo để xem bảng điều khiển
A.Mở terminal đúng 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 thư mục dự án trước khi chạy. Ví dụ:
cd duong-dan-toi-du-an-cua-banThay duong-dan-toi-du-an-cua-ban bằng đường dẫn thật trên máy bạn.
B.Chạy lệnh init
Đây là lệnh chính trong README:
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. README cho biết đường cài này tạo các thư mục và file như .claude/, .claude-flow/, CLAUDE.md, các helper và settings trong workspace của bạn. Nếu dự án của bạn đã có CLAUDE.md, hãy sao lưu hoặc đưa dự án vào git trước khi chạy để dễ so sánh thay đổi. Đây là lời khuyên của mình, README không yêu cầu.
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.Khởi động lại Claude Code
Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code lúc chạy init, hãy thoát ra mở lại.
D.Đường thay thế: chỉ cài plugin trong Claude Code
Cách này không thêm file nào vào dự án. Nó cài công cụ lõi, console và mod. Gõ lần lượt 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
/rufloNếu Claude Code của bạn từ 2.1.292 trở lên, README cũng cho phép cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloBảng so sánh trong README tóm tắt khác biệt: đường plugin nhẹ, không tạo file, không cài hook, chỉ có MCP server nếu bạn cài ruflo-core. Đường CLI init thì đầy đủ vòng lặp, README gọi là cách dùng cho môi trường thật.
E.Đường thay thế: Codex hoặc client MCP khác
Với Codex hoặc client MCP khác mà không muốn thiết lập dự án, README hướng dẫn cấu hình command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Cách điền cụ thể phụ thuộc vào giao diện cấu hình MCP của từng client. README chưa chỉ chi tiết cho từng client trong phần mình có. Bạn xem thêm tài liệu của client đó.
F.Chạy bảng điều khiển ngoài Claude Code
Console cũng chạy độc lập trong terminal:
npx ruflo tuiThêm --plain nếu muốn in ra một khung hình duy nhất để dùng trong script.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh "kiểm tra phiên bản" riêng, nên cách kiểm tra dưới đây dựa trên những gì tư liệu nói:
- Sau
init: trong thư mục dự án phải xuất hiện các mục mà README liệt kê như.claude/,.claude-flow/vàCLAUDE.md. - Trong Claude Code: khởi động lại rồi gõ
/ruflo. README nói đây là cách mở bảng điều khiển. - Với cách cài plugin: gõ
/pluginđể mở danh sách và xác nhận các plugin xuất hiện trong dòng "active mods" (README ghi như vậy). - Với
tui: chạynpx ruflo tuivà xem có hiện giao diện console không.
Nếu cả ba điều trên không xảy ra, xem phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
A.Rà soát một repo và viết test cho chỗ rủi ro
Bối cảnh: bạn là lập trình viên nhận lại một dự án cũ, không rõ chỗ nào dễ hỏng. Sau khi chạy init và mở lại Claude Code, bạn dùng đú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 theo README: một nhóm agent cùng làm, tìm module rủi ro nhất, viết test và tóm tắt những gì đã đổi. Bạn nên đọc kỹ tóm tắt và chạy lại test trước khi gộp vào nhánh chính. Kết quả cụ thể phụ thuộc vào dự án và mô hình bạn đang dùng.
Mô hình lo phần viết, còn harness lo phần để nó làm việc thật.
Ông T
B.Tạo một "mission" và giữ quyền kiểm soát
Bối cảnh: bạn muốn thử cho Claude điều khiển console nhưng chưa dám cho toàn quyền. README có một quy trình nhỏ để thử:
- Cài console bằng các lệnh plugin ở trên, mở
/ruflo, chọn Settings → Claude control → write + ask. - Đưa 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 trong console.
- Kiểm tra mục Missions có mục tiêu mới và Overview ghi lại hành động.
Lưu ý README nói rõ: tạo mission không có nghĩa là tính năng đã được làm. Nó chỉ ghi nhận mục tiêu. Nếu muốn dừng, bấm "Take back control"; các lệnh gọi sau đó của Claude sẽ bị từ chối cho đến khi bạn bật lại.
C.Dùng Ruflo từ Codex hoặc một công cụ MCP khác
Bối cảnh: nhóm bạn không chỉ dùng Claude Code mà còn dùng Codex. Thay vì cài init vào từng dự án, bạn khai báo MCP server trong client với command npx và đối số ["-y", "ruflo@latest", "mcp", "start"]. Khi client khởi động, nó chạy Ruflo như một MCP server và các công cụ của Ruflo xuất hiện để gọi. Cách này hợp khi bạn chỉ muốn thử công cụ mà không để lại file trong dự án.
D.Thử từng plugin nhỏ không đụng vào dự án
Bối cảnh: bạn chỉ cần một chức năng, ví dụ tìm chỗ thiếu test, hoặc theo dõi chi phí token. README có plugin ruflo-testgen (tìm test còn thiếu và tạo chúng) và ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí). Bạn cài theo mẫu đã có:
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@rufloSau đó cài thêm plugin cần dùng theo đúng dạng /plugin install <tên-plugin>@ruflo, tên lấy từ bảng plugin trong README. README cũng nói trong console, /ruflo market là danh mục plugin với các nút cài, bật, tắt và cập nhật, và mỗi hành động đều hỏi xác nhận.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh npx báo lỗi hoặc không chạy
Nguyên nhân thường gặp là Node quá cũ. package.json yêu cầu Node 20 trở lên. Hãy kiểm tra phiên bản bằng node --version và nâng cấp nếu cần. Ngoài ra, nếu bạn chạy ở thư mục không phải dự án, hãy cd vào đúng nơi rồi chạy lại.
B.Claude Code không thấy agent hay lệnh /ruflo
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 đã chạy init. Nếu dùng cách plugin, chạy /reload-plugins và kiểm tra /plugin. Đồng thời xem phiên bản Claude Code có đạt mức tối thiểu (2.1.287 cho đường plugin) hay không.
C.Lệnh /plugin install báo không tìm thấy
Bạn cần chạy /plugin marketplace add ruvnet/ruflo trước thì các lệnh @ruflo mới có nguồn để cài. Cũng lưu ý lệnh này gõ bên trong Claude Code, không gõ trong terminal thường. Với lệnh claude plugin install ... ở terminal thì cần Claude Code từ 2.1.292.
D.Cài cùng một plugin từ hai nơi
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 nguồn gốc của chúng hoặc ruflo. Nếu bật từ cả hai, mod và lệnh sẽ bị tải hai lần. Hãy gỡ một bản.
E.Dự án bị thêm file ngoài ý muốn
Đường init thêm khá nhiều thứ vào workspace (.claude/, .claude-flow/, CLAUDE.md, settings). Hãy chạy trong một dự án đã commit để xem được thay đổi và hoàn tác nếu cần. Nếu bạn chỉ muốn thử, đường plugin không thêm file vào dự án.
VII.Có nên dùng không
Điểm mạnh. Cài vào rất gọn, chỉ một lệnh. Có nhiều đường vào cho người dùng khác nhau: dự án đầy đủ, plugin nhẹ, MCP cho Codex, giao diện terminal riêng. Cơ chế quyền trong console rõ ràng (mức quyền cộng chế độ ask hoặc auto) và có nút lấy lại quyền điều khiển. Giấy phép MIT, repo đông người theo dõi và vẫn được cập nhật.
Giới hạn. Hệ thống rất lớn: hàng chục plugin, hàng trăm công cụ MCP, nhiều khái niệm như swarm, federation, bộ nhớ vector. Với người mới, phần lớn chưa cần đến. README cũng tự nói một số video demo dùng dữ liệu mẫu và không chứng minh swarm đã hoàn thành việc thật hay bộ nhớ đã nhớ lại được. Phần học và bộ nhớ có điều kiện cấu hình. Mod chạy với quyền tài khoản của bạn, không có sandbox. Mình chưa có thông tin về chi phí token thực tế khi chạy nhiều agent cùng lúc, nên bạn theo dõi sát khi thử.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code trả lời từng câu lệnh nhỏ, bạn chưa cần Ruflo. Nếu bạn không dùng Claude Code hay Codex, repo này không phải công cụ độc lập cho bạn. Lời khuyên của mình: thử trước trên một dự án nhỏ đã commit, giữ quyền ở mức read + ask, rồi mới mở rộng dần.
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 dùng mã nguồn miễn phí. Tuy nhiên tư liệu chưa nói về chi phí của các dịch vụ đi kèm, và bạn vẫn cần Claude Code hoặc Codex theo gói của chính các công cụ đó. Plugin ruflo-cost-tracker giúp theo dõi token và đặt ngân sách.
Cài Ruflo cần phiên bản Node nào?
package.json yêu cầu Node từ 20.0.0 trở lên. Bạn chạy lệnh cài bằng npx ruflo@latest init trong thư mục dự án. Nếu dùng đường chỉ cài plugin, Claude Code cần từ 2.1.287 trở lên.
Ruflo có 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à dùng cơ bản. Một plugin trong danh sách (ruflo-ruvector) có nhắc tìm kiếm dùng GPU tăng tốc, nhưng README không nói đó là bắt buộc.
Ruflo chạy được trên Windows không?
README phần mình có chưa nêu rõ hệ điều hành được hỗ trợ. Lệnh cài chỉ là npx nên cần Node 20 trở lên. Nếu bạn dùng Windows, hãy thử trên một dự án nhỏ và xem tài liệu trong repo để biết thêm.
Dùng Ruflo có làm thay đổi dự án của tôi không?
Có, nếu bạn cài bằng npx ruflo@latest init. README nói nó thêm .claude/, .claude-flow/, CLAUDE.md, helper và settings vào dự án. Cách chỉ cài plugin trong Claude Code thì không thêm file nào vào workspace.
Ruflo khác gì dùng Claude Code thuần?
Claude Code là công cụ để mô hình viết và sửa code. Ruflo là lớp bọc thêm đội agent, bộ nhớ, hook, MCP server và bảng điều khiển để điều phối việc lớn. Bạn vẫn dùng Claude Code như bình thường, README nói hook sẽ tự định tuyến và phối hợp ở phía sau.
Cho Claude điều khiển console có an toàn không?
README nói mặc định hiện tại là quyền read với chế độ ask. Các hành động vượt mức quyền bị từ chối, còn hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần xác nhận kể cả khi để auto. 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 có sandbox.


