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: lớp công cụ bao quanh Claude Code và Codex, thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên và máy chủ MCP. Bạn chỉ cần chạy một lệnh npx trong thư mục dự án rồi dùng Claude Code như bình thường. Cài không khó, nhưng cần Node 20 trở lên và nên đọc kỹ phần quyền hạn trước khi bật các tính năng tự động.
Ruflo là một "agent harness" mã nguồn mở, viết bằng TypeScript: nó đứng quanh Claude Code và Codex để thêm đội agent, bộ nhớ, hook và máy chủ MCP vào dự án của bạn. Hiểu đơn giản: mô hình AI lo phần viết, còn Ruflo lo phần công cụ, trí nhớ, vòng lặp và giới hạn để AI làm việc có tổ chức hơn. Tác giả giới thiệu nó là "agent meta-harness" cho Claude Code và Codex.
Bạn nên xem repo này nếu đã dùng Claude Code (hoặc Codex) và thấy mỗi phiên làm việc lại phải giải thích từ đầu, hoặc muốn giao một việc lớn cho nhiều agent cùng làm. Người mới cũng thử được, vì README nhấn mạnh: sau khi chạy lệnh khởi tạo, bạn cứ dùng Claude Code như thường, phần định tuyến và phối hợp agent chạy ngầm. 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.
Điểm đáng giá nhất là cách cài rất gọn: một lệnh npx ruflo@latest init trong thư mục dự án. Repo hiện có khoảng 81.582 sao và 9.607 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây. Một lưu ý từ đầu: Ruflo có rất nhiều thứ (hàng chục plugin, nhiều tính năng nâng cao). Bài này chỉ tập trung vào phần bạn cài và dùng được ngay.
ruvnet/ruflo
Ruflo là bộ khung bao quanh Claude Code và Codex, thêm đội agent, bộ nhớ, hook và bảng điều khiển. Cài bằng một lệnh npx.
I.Ruflo làm được gì
Thêm đội agent chuyên biệt cho Claude Code. README nói gói đầy đủ có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: thay vì một AI làm mọi thứ, bạn có thể yêu cầu một "swarm" (nhóm agent) cùng xem xét, viết test và tóm tắt.
Bộ nhớ qua nhiều phiên. Ruflo có bộ nhớ dạng vector để agent nhớ kinh nghiệm từ lần trước. Bạn đỡ phải giải thích lại bối cảnh. README cũng ghi rõ phần học tự động này là "conceptual learning loop", và vẫn cần embedding cùng các module học được cấu hình. Đừng kỳ vọng nó thần kỳ ngay.
Hook tự định tuyến việc. Sau init, hook sẽ tự chọn cách xử lý cho từng tác vụ và học từ các lần thành công. Bạn không phải gọi từng agent bằng tay.
Máy chủ MCP cho nhiều công cụ. Ruflo có sẵn MCP server. Nhờ vậy Codex hoặc bất kỳ ứng dụng nào hỗ trợ MCP cũng nối vào được bằng một lệnh npx.
Bảng điều khiển (console) ngay cạnh Claude Code. Bạn xem được workflow, agent, mô hình, token và chi phí. Bạn cũng mở được log của từng lần chạy, tìm kiếm, xem lại và so sánh. Console còn chạy độc lập ở terminal thường.
Cho Claude điều khiển console, nhưng bạn đặt giới hạn. Bật mục Claude control trong Settings, chọn mức read, write, manage hoặc full, và chế độ duyệt ask hoặc auto. Mặc định hiện tại là read + ask. Các hành động 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 lớn. README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps… Ví dụ ruflo-testgen tìm test còn thiếu, ruflo-cost-tracker theo dõi token và đặt ngân sách, ruflo-aidefence chặn prompt injection.
II.Cần chuẩn bị gì
- Node.js 20 trở lên.
package.jsoncủa repo yêu cầu>=20.0.0. Lệnhnpxđi kèm Node. - Claude Code nếu bạn muốn dùng theo hướng chính của README. Riêng đường cài bằng plugin cần Claude Code 2.1.287 trở lên. Lệnh
claude plugin installtừ terminal cần 2.1.292 trở lên. - Một thư mục dự án để chạy
init. README ghi lệnh này thêm file vào dự án. - Codex hoặc ứng dụng MCP khác thì chỉ cần cấu hình được lệnh khởi chạy MCP (nêu ở phần dưới).
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 API key bắt buộc. Nếu bạn dùng thêm các plugin gọi mô hình bên ngoài, hãy xem tài liệu của từng plugin để biết cần tài khoản hay key nào.
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 initThêm agent, hook, bộ nhớ và MCP server vào dự án
- Khởi động lại Claude CodeĐể nó nhận cấu hình mới trong cùng thư mục
- Giao một việc thậtGõ yêu cầu dùng swarm của Ruflo
- (Tuỳ chọn) Mở /rufloXem bảng điều khiển sau khi cài console
A.Mở terminal đúng thư mục dự án
Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. init ghi file vào thư mục hiện tại, nên bạn cần đứng đúng trong dự án của mình. Ví dụ với một dự án đã có sẵn trên máy (thay tên thư mục cho đúng):
cd ten-thu-muc-du-anNếu bạn muốn thử trên chính mã nguồn Ruflo thì tải về bằng lệnh phổ thông sau, nhưng với dùng thật bạn không cần bước này:
git clone https://github.com/ruvnet/ruflo.gitB.Chạy lệnh khởi tạo
Đây là lệnh chính theo README:
npx ruflo@latest initLệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. README cho biết gói đầy đủ tạo các thư mục như .claude/, .claude-flow/, file CLAUDE.md, các helper và settings trong workspace của bạn. Vì vậy hãy chạy trong dự án có quản lý phiên bản (git) để dễ xem file nào mới xuất hiện.
Nếu muốn cấu hình tương tác từng mục, README có lệnh riêng:
npx ruflo@latest init wizardC.Mở lại Claude Code và giao việc
Mở Claude Code trong cùng 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 đang mở sẵn thì hãy thoát rồi vào lại. Sau đó đưa cho nó một việc thật, ví dụ 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.Bạn có thể viết yêu cầu bằng tiếng Việt, nhưng README chỉ đưa ví dụ tiếng Anh. Nếu thấy kết quả chưa như ý, thử dùng đúng câu mẫu trên để kiểm tra trước.
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. Nó cài công cụ lõi, bảng điều khiển và các mod. Gõ từng dòng 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
/rufloNếu dùng Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloCác mod chạy với quyền của tài khoản bạn và không bị cô lập (sandbox). README khuyên đọc mã của mod trước khi cài. Hãy làm vậy, nhất là trên máy có dữ liệu công việc.
Bảng trong README so sánh hai đường: cài plugin cho bạn lệnh gạch chéo và vài skill, không có hook, và chỉ có MCP server khi cài ruflo-core. Cài bằng npx ruflo init cho toàn bộ vòng làm việc gồm agent, lệnh, skill, MCP, hook và daemon. README khuyên đường này cho dùng nghiêm túc.
E.Nối Codex hoặc ứng dụng MCP khác
Không cần cài vào dự án. Trong phần cấu hình MCP của ứng dụng, đặt command là npx và arguments như sau:
["-y", "ruflo@latest", "mcp", "start"]Tương đương dòng lệnh đầy đủ:
npx -y ruflo@latest mcp startF.Chạy bảng điều khiển trong terminal thường
Không cần Claude Code cũng mở được console:
npx ruflo tuiThêm --plain nếu bạn chỉ muốn in ra một khung hình, tiện cho script.
IV.Kiểm tra đã chạy được chưa
README không đưa một dòng "thành công" cố định, nên bạn kiểm tra theo các dấu hiệu sau:
- Sau
npx ruflo@latest init, trong thư mục dự án phải xuất hiện các thư mục và file như.claude/,.claude-flow/,CLAUDE.md. README liệt kê đúng những thứ này cho đường cài bằng CLI. - Mở lại Claude Code trong thư mục đó rồi gõ
/ruflo. Với đường plugin, README nói bạn có thể mở/pluginđể xác nhận các plugin hiện trong dòng mod đang bật. - Giao việc mẫu ở trên. Nếu Claude Code bắt đầu dùng swarm và đưa ra báo cáo, vậy là đã nối được.
- Với MCP client, kiểm tra ứng dụng đã liệt kê được máy chủ ruflo sau khi cấu hình.
Nếu chỉ muốn xác nhận công cụ chạy được mà chưa đụng vào dự án, hãy thử npx ruflo tui --plain.
V.Dùng vào việc thật
A.Lập trình viên cần rà soát một dự án thừa kế
Bạn vừa nhận một repo cũ, không ai nhớ module nào dễ hỏng. Sau khi cài xong, bạn mở Claude Code trong thư mục đó và đưa prompt 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: nhóm agent xác định module rủi ro nhất, viết test cho nó và tóm tắt phần đã sửa. Hãy đọc kỹ phần tóm tắt và xem lại các thay đổi bằng git trước khi giữ lại.
Agent = Model + Harness: mô hình lo viết, còn Ruflo lo công cụ, bộ nhớ và giới hạn để nó làm việc có tổ chức.
Ông T
B.Người quản lý dự án muốn theo dõi việc AI đang làm
Bạn không viết code nhưng muốn biết AI đang làm gì và tốn bao nhiêu. Cài console theo đường plugin, mở /ruflo, bạn sẽ thấy workflow, agent, mô hình, token và chi phí cạnh Claude Code. Bạn mở log của từng lần chạy để xem kết quả và tìm chỗ thất bại. Nếu thiên về dòng lệnh, npx ruflo tui cho bảng tương tự ngay trong terminal.
C.Tạo một "mission" bằng Claude, có kiểm soát
Đây là kịch bản README mô tả thành từng bước. Nó phù hợp nếu bạn muốn thử cho Claude điều khiển console nhưng vẫn nắm quyền:
- Cài console, mở
/ruflo, vào Settings → Claude control và chọn write + ask. - Gõ yêu cầu: "Create a mission to add a dark mode toggle. Show me the mission and its status."
- Khi 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 ý README nhấn mạnh: tạo mission không có nghĩa tính năng đã được làm xong. Bạn muốn dừng bất cứ lúc nào thì bấm Take back control, khi đó các lời gọi tiếp theo của Claude sẽ bị từ chối.
D.Dùng Ruflo từ Codex hoặc công cụ khác
Bạn dùng Codex thay vì Claude Code. Bạn cấu hình MCP với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"]. Từ đó Codex gọi được các công cụ MCP của Ruflo mà không cần thêm file nào vào dự án. README cũng có đường riêng cho Grok Build: npx ruflo init --grok chỉ ghi vào dự án, và bạn thêm --dry-run để xem trước.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx báo lỗi phiên bản hoặc không chạy. Repo yêu cầu Node 20 trở lên. Kiểm tra bằng node --version, nếu thấp hơn thì nâng Node rồi chạy lại.
Lệnh /plugin hoặc claude plugin install không nhận. Đường plugin cần Claude Code 2.1.287 trở lên, còn lệnh từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước.
Cài xong mà không thấy gì mới. Claude Code chỉ nhận cấu hình ở lần khởi động tiếp theo. Với đường plugin, chạy /reload-plugins, rồi mở /plugin để xem plugin đã nằm trong danh sách đang bật chưa.
Một plugin bị nạp hai lần. README cảnh báo các plugin bên ngoài như agentic-qe-fleet, agentdb, agentic-flow chỉ nên cài từ một marketplace, hoặc từ marketplace gốc của chúng, hoặc từ ruflo. Cài từ cả hai thì mod và lệnh bị nạp hai lần.
Gọi công cụ MCP bị lệch tên. Khi chỉ cài ruflo-core qua plugin, tên công cụ có dạng mcp__plugin_ruflo-core_ruflo__memory_store, không phải tên ngắn như memory_store. Muốn dùng đúng tên như tài liệu của đường CLI, hãy cài bằng npx ruflo init.
Claude từ chối thực hiện thao tác trong console. Hành động vượt mức quyền bạn đặt sẽ bị từ chối. Đó là thiết kế, không phải lỗi. Nâng mức quyền trong Settings → Claude control nếu bạn thực sự muốn, và nên giữ chế độ ask.
VII.Có nên dùng không
Điểm mạnh. Cài nhanh bằng một lệnh. Giấy phép MIT. Repo hoạt động đều. Hỗ trợ cả Claude Code lẫn Codex qua MCP. Có bảng điều khiển để theo dõi chi phí và log. Mô hình phân quyền cho Claude (mặc định read + ask) khá thận trọng.
Giới hạn. Ruflo rất rộng: nhiều plugin, nhiều khái niệm (swarm, federation, bộ nhớ vector). Người mới dễ bị ngợp nếu cố hiểu hết một lần. Phần "tự học" theo chính README là khái niệm và cần cấu hình thêm. Các bản ghi demo trong repo dùng dữ liệu mẫu hoặc phát lại khung hình, README nói rõ chúng không phải bằng chứng cho việc swarm đã hoàn thành công việc hay bộ nhớ gợi lại được. Đường cài đầy đủ còn thêm khá nhiều file vào dự án. Mod chạy với quyền tài khoản của bạn và không có sandbox.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code làm vài việc nhỏ, dùng thẳng Claude Code có thể đủ. Nếu bạn không muốn thêm file nào vào dự án, hãy thử đường plugin trước. Còn nếu ngại cài thứ chạy không sandbox, hãy chạy thử trên một dự án nháp, không có dữ liệu quan trọng, trước khi dùng thật.
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 tư liệu không nói gì về chi phí gọi mô hình AI. Bạn vẫn cần tài khoản hoặc gói của Claude Code, Codex hay dịch vụ khác mà bạn nối vào.
Cài Ruflo có khó không?
Đường cài chính chỉ là một lệnh `npx ruflo@latest init` chạy trong thư mục dự án, rồi mở lại Claude Code. Bạn cần Node 20 trở lên. Phần khó nằm ở việc tìm hiểu các tính năng nâng cao, không phải ở bước cài.
Ruflo khác gì Claude Code thông thường?
Theo README, Claude Code là phần mô hình và giao diện, còn Ruflo là lớp bao quanh. Nó thêm đội agent, bộ nhớ qua các phiên, hook tự định tuyến, máy chủ MCP và bảng điều khiển. Bạn vẫn dùng Claude Code như bình thường sau khi cài.
Có 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 ứng dụng MCP khác dùng được bằng cách cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. README cũng có hướng dẫn riêng cho Grok Build với lệnh `npx ruflo init --grok`.
Cài Ruflo có làm thay đổi dự án của tôi không?
Có nếu bạn dùng `npx ruflo init`: README nói nó thêm `.claude/`, `.claude-flow/`, `CLAUDE.md`, các helper và settings. Nếu muốn không thêm file nào, README có đường cài plugin trong Claude Code, với mô tả là không có file nào trong workspace.
Có an toàn không? Claude có tự ý làm gì trong bảng điều khiển không?
Mặc định Claude control ở mức read cùng chế độ hỏi lại (ask). Hành động vượt mức quyền bị từ chối, và hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả ở chế độ auto. Riêng các 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 mã trước khi cài.
Chạy được trên Windows không, có cần GPU không?
Phần tư liệu hiện có không nêu hệ điều hành hỗ trợ hay yêu cầu GPU, nên chưa có thông tin chắc chắn. Điều README có nói là cần Node 20 trở lên và, với đường plugin, Claude Code 2.1.287 trở lên. Bạn nên xem README đầy đủ trong repo trước khi cài trên máy đặc thù.


