ruflo: bộ khung điều phối nhiều 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 là một agent harness (bộ khung điều phối) viết bằng TypeScript, đặt quanh Claude Code và Codex để thêm agent chuyên biệt, nhóm agent phối hợp (swarm), bộ nhớ lâu dài và các lớp kiểm soát an toàn. Cách cài nhanh nhất là chạy một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node từ 20 trở lên. Cài không khó, nhưng bộ công cụ rất rộng nên người mới nên bắt đầu từ một tác vụ nhỏ.
Ruflo là một "agent harness", tức bộ khung bọc quanh Claude Code và Codex. Mô hình AI chỉ biết viết. Ruflo cho nó thêm công cụ, bộ nhớ, vòng lặp làm việc và các lớp kiểm soát để làm được việc dài hơi. Repo hiện có khoảng 81.588 sao và 9.608 fork, giấy phép MIT, viết chủ yếu bằng TypeScript.
Vấn đề repo giải quyết khá quen thuộc. Bạn dùng Claude Code, giao một việc lớn, rồi thấy nó quên ngữ cảnh giữa các phiên, làm tuần tự từng việc, và bạn phải tự dặn lại mọi thứ. Ruflo thêm các agent chuyên biệt, cho chúng làm việc theo nhóm (swarm), và ghi nhớ kinh nghiệm từ những lần làm trước.
Ai nên dùng? Lập trình viên đã dùng Claude Code hoặc Codex và muốn nó phối hợp nhiều agent hơn. Người làm kinh doanh hay văn phòng có thể thử được, nhưng cần quen việc mở terminal trước. Điểm đáng giá nhất là bạn chỉ cần một lệnh init, sau đó vẫn dùng Claude Code như bình thường, còn phần điều phối chạy ngầm.
ruvnet/ruflo
Bộ khung (harness) bọc quanh Claude Code và Codex: thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua các phiên, cài bằng một lệnh npx.
I.Ruflo làm được gì
Theo README, sau khi cài 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. Phần dưới là những nhóm tính năng đáng biết nhất.
Agent chuyên biệt và swarm. Ruflo thêm hơn 100 agent theo từng vai trò. Chúng tự tổ chức thành nhóm để chia việc. Với bạn, lợi ích là một yêu cầu lớn như "rà soát cả repo" được chia cho nhiều agent thay vì một agent làm tuần tự.
Bộ nhớ qua các phiên. Ruflo lưu lại kinh nghiệm và truy xuất bằng tìm kiếm vector. Lần sau gặp việc tương tự, agent không phải bắt đầu từ số không. README lưu ý rằng phần truy xuất vector cục bộ có thể chạy mà không cần LLM, nhưng vẫn cần embedding và các module học đã được cấu hình.
Hooks tự định tuyến. Sau init, hệ thống hook tự chọn cách giao việc, học từ các mẫu làm việc thành công và phối hợp agent ở chế độ nền. Bạn không phải gõ lệnh riêng cho từng việc.
Bảng điều khiển (console) ngay cạnh Claude Code. Console hiển thị workflow, agent, model, token và chi phí. Bạn có thể mở log của từng lần chạy, tìm kiếm, xem lỗi, phát lại và so sánh. Lệnh mở là /ruflo.
Cho Claude điều khiển console nhưng bạn đặt giới hạn. Trong Settings có mục "Claude control" với bốn mức quyền: read, write, manage, full. Có hai kiểu duyệt: ask (hỏi bạn) hoặc auto. README nói mặc định hiện tại là read + ask. Các hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận, kể cả ở chế độ auto.
Hệ plugin. Ngoài cách cài đầy đủ, bạn có thể cài lẻ từng plugin cho Claude Code, chẳng hạn ruflo-swarm (nhóm agent), ruflo-rag-memory (truy xuất thông minh), ruflo-testgen (tìm chỗ thiếu test và sinh test), ruflo-cost-tracker (theo dõi token, đặt ngân sách), ruflo-security-audit (quét lỗ hổng). README liệt kê tổng cộng 48 plugin, cộng thêm 3 plugin bên ngoài.
Liên kết nhiều máy (federation). Agent trên các máy khác nhau có thể trao đổi với nhau. README nói việc này được thiết kế để không làm lộ dữ liệu. Nếu chỉ dùng cá nhân, bạn có thể bỏ qua phần này.
Tương thích nhiều client. Ngoài Claude Code, Ruflo chạy với Codex và các client MCP khác. README còn có lệnh riêng cho Grok Build.
II.Cần chuẩn bị gì
Tư liệu repo nêu rõ những điều sau:
- Node.js 20 trở lên.
package.jsonyêu cầu>=20.0.0. Bạn dùngnpxđể chạy nên cần Node đi kèm npm. - Claude Code, nếu bạn đi theo đường cài bằng plugin: README yêu cầu bản 2.1.287 trở lên. Riêng lệnh cài từ terminal (
claude plugin install ...) cần bản 2.1.292 trở lên. - Một thư mục dự án để chạy
init, vì lệnh này thêm file vào chính thư mục đó. - Codex hoặc client MCP khác, nếu bạn không dùng Claude Code.
Về hệ điều hành, GPU hay dung lượng ổ đĩa, README phần đã cung cấp chưa nói gì cụ thể, nên mình không khẳng định. Về API key: README không yêu cầu key riêng cho Ruflo ở phần cài nhanh. Tuy vậy Claude Code hay Codex của bạn vẫn cần tài khoản và gói dùng của chính chúng.
Các agent chạy tự động có thể dùng nhiều token. Nên bật theo dõi chi phí (plugin ruflo-cost-tracker) và giữ quyền Claude control ở mức thấp khi mới thử. Các mod trong Ruflo chạy bằng quyền tài khoản của bạn và không bị cách ly (sandbox), nên hãy đọc code trước khi cài.
III.Cài đặt từng bước
README có ba đường cài. Mình xếp theo thứ tự dễ nhất trước.
- Mở terminal đúng thư mụcĐứng trong thư mục dự án bạn muốn dùng Ruflo
- Chạy initMột lệnh npx thêm agent, hook, bộ nhớ và MCP server vào dự án
- Mở lại Claude CodeKhởi động Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc thậtDùng câu lệnh mẫu để Ruflo điều phối swarm
- (Tuỳ chọn) Cài consoleDùng plugin để có bảng điều khiển /ruflo
A.Mở terminal đúng thư mục
Đây là chỗ người mới hay vấp nhất. 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. Nếu chưa có dự án, hãy tạo một thư mục thử nghiệm riêng, đừng chạy trong thư mục chứa dữ liệu quan trọng.
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 của README:
npx ruflo@latest initnpx tải Ruflo bản mới nhất rồi chạy lệnh init. 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 này tạo các thư mục .claude/, .claude-flow/, file CLAUDE.md, các file hỗ trợ và file cài đặt trong dự án của bạn. Nếu dự án đã có CLAUDE.md, bạn nên sao lưu hoặc dùng git để xem lại thay đổi.
Muốn thiết lập theo kiểu hỏi đáp từng bước, README có lệnh:
npx ruflo@latest init wizardC.Mở lại Claude Code
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ếu Claude Code đang mở sẵn, hãy thoát rồi mở lại.
D.Giao thử một việc thật
Dán câu 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.Câu này yêu cầu Ruflo rà repo, tìm module rủi ro nhất, viết test cho nó rồi tóm tắt thay đổi. Bạn có thể viết bằng tiếng Việt, nhưng README chỉ đưa ví dụ tiếng Anh nên mình giữ nguyên bản mẫu.
E.Cách khác: chỉ cài plugin vào Claude Code
Đường này không thêm file nào vào dự án. Nó cài công cụ lõi, console và các mod. Hãy chạy các lệnh sau bên trong Claude Code (nhớ cần bản 2.1.287 trở lên):
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/rufloHai lệnh đầu thêm kho plugin rồi cài ruflo-core. Hai lệnh tiếp theo cài console và mod. /reload-plugins nạp lại, còn /ruflo mở bảng điều khiển. Các lệnh bắt đầu bằng / gõ trong khung chat của Claude Code, không gõ ở terminal thường.
Từ terminal thường, trên Claude Code 2.1.292 trở lên, README cho lệnh:
claude plugin install ruflo-core@ruflo --marketplace ruvnet/rufloBảng so sánh trong README cho thấy đường plugin gọn hơn nhưng nhẹ hơn: không cài hook và không có đủ vòng lặp. README mô tả đường npx ruflo init là đường dành cho dùng thực tế, vì mọi thứ hoạt động như tài liệu mô tả.
F.Cách khác: Codex hoặc client MCP khác
Với Codex hay bất kỳ client MCP nào, README hướng dẫn cấu hình command là npx và arguments là:
["-y", "ruflo@latest", "mcp", "start"]Tương đương một dòng lệnh là npx -y ruflo@latest mcp start. Chỗ điền cấu hình cụ thể khác nhau tuỳ client, bạn xem phần thêm MCP server trong tài liệu của client đó.
G.Cách khác: chạy console ở 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 nếu bạn muốn in ra đúng một khung hình để 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" duy nhất, nên bạn dựa vào các dấu hiệu sau.
- Sau
npx ruflo@latest init, trong thư mục dự án phải xuất hiện.claude/,.claude-flow/vàCLAUDE.md(theo bảng so sánh của README). Kiểm tra bằng cách mở thư mục hoặc chạyls. - Mở lại Claude Code rồi gõ
/ruflo. Nếu bảng điều khiển hiện ra thì phần console đã hoạt động. - Với đường plugin, gõ
/pluginvà xemruflo-consolecùngruflo-modscó nằm trong dòng các mod đang bật hay không. - Giao câu mẫu ở trên và xem Claude Code có chạy theo hướng swarm không. Lưu ý README thừa nhận các animation trong repo dùng dữ liệu mẫu. Chúng không chứng minh swarm đã hoàn thành việc thật, nên hãy tự kiểm tra kết quả trong code của bạn.
V.Dùng vào việc thật
Các tình huống dưới đây chỉ dùng những khả năng có trong README.
A.Dev nhận một repo lạ và cần biết chỗ nào rủi ro
Bạn vừa nhận một dự án cũ, ít test. Hãy chạy npx ruflo@latest init trong thư mục dự án, mở lại Claude Code, rồi giao đúng câu mẫu:
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.Kết quả bạn nhận: Claude Code chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Hãy đọc kỹ cả test lẫn bản tóm tắt trước khi gộp vào nhánh chính.
Agent = Model + Harness. Model viết, còn harness cho nó tay chân để làm việc thật.
Ông T
B.Quản lý dự án muốn xem agent đang làm gì và tốn bao nhiêu
Bạn không viết code nhưng muốn nhìn tiến độ. Cài console bằng plugin (ruflo-console), mở /ruflo và xem workflow, agent, model, token, chi phí. Khi một lần chạy có vấn đề, mở log của agent đó, tìm kiếm hoặc phát lại để biết nó hỏng ở bước nào. Kết quả là bạn có một chỗ nhìn chung, thay vì đoán qua đoạn chat dài.
C.Cho Claude tạo "mission" trong console, có kiểm soát
README có một bài thử từng bước rất an toàn. Cài console, mở /ruflo, vào Settings → Claude control và chọn write + ask. Sau đó nhờ Claude:
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ờ. Cuối cùng, kiểm tra mục Missions có mục tiêu đó và mục 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. Muốn dừng, bấm Take back control và các lệnh sau đó của Claude sẽ bị từ chối cho đến khi bạn cấp lại quyền.
D.Người dùng Codex muốn thêm bộ nhớ và agent
Bạn đang dùng Codex thay vì Claude Code. Thêm một MCP server với command npx và arguments ["-y", "ruflo@latest", "mcp", "start"] vào client của bạn. Khi đó công cụ của Ruflo có thể gọi được từ client đó. Phạm vi từng công cụ cụ thể, bạn xem trong tài liệu đi kèm trong repo, vì phần README đã cung cấp chưa liệt kê chi tiết.
VI.Lỗi hay gặp và cách xử lý
Lệnh npx báo lỗi hoặc không chạy được. Nguyên nhân dễ gặp nhất là Node quá cũ. package.json yêu cầu Node từ 20 trở lên. Chạy node --version để kiểm tra, nâng cấp nếu cần rồi chạy lại lệnh.
Cài xong mà Claude Code không thấy agent hay lệnh mới. 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 Claude Code, mở lại đúng thư mục đã chạy init. Với đường plugin, chạy thêm /reload-plugins.
Lệnh /plugin hoặc claude plugin install không hoạt động. Có thể Claude Code của bạn quá cũ. Đường plugin cần bản 2.1.287 trở lên, riêng lệnh cài từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước.
Claude từ chối thực hiện một hành động trong console. Đây là thiết kế, không phải lỗi. Hành động vượt quá mức quyền bạn đặt sẽ bị từ chối, còn hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần bạn xác nhận. Nếu cần, nâng mức quyền trong Settings → Claude control, nhưng hãy cân nhắc kỹ và giữ chế độ ask.
Một plugin bên ngoài bị nạp hai lần. README cảnh báo với các plugin như agentic-qe-fleet, agentdb, agentic-flow: chỉ nên cài từ một kho duy nhất. Nếu bật từ cả hai kho, mod và lệnh của nó sẽ bị nạp hai lần. Hãy tắt một trong hai bản.
Thư mục dự án bị thêm nhiều file ngoài ý muốn. Đường npx ruflo init thêm file vào dự án. Hãy chạy nó trong một nhánh git hoặc thư mục thử nghiệm trước. Nếu muốn không thêm file nào, dùng đường plugin. Riêng lệnh init --grok, README nói có thể thêm --dry-run để xem trước.
VII.Có nên dùng không
Điểm mạnh. Cài đặt bằng một lệnh. Dùng được với Claude Code, Codex và client MCP khác. Có nhiều lựa chọn cho người cần ít can thiệp (plugin) lẫn người cần đầy đủ (init). Có công cụ nhìn lại chi phí, log và giới hạn quyền cho Claude. 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 lớn, với hàng chục plugin và hàng trăm công cụ, nên người mới dễ bị ngợp. Một số phần như federation hay các plugin chuyên biệt cần đọc tài liệu riêng. README cũng tự nói rõ một số demo dùng dữ liệu mẫu, nên đừng xem chúng là bằng chứng cho kết quả thật. Mình chưa có số liệu độc lập về hiệu quả hay mức tiêu tốn token trong dùng thực tế, nên hãy thử trên dự án nhỏ và theo dõi chi phí.
Khi nào chọn cách khác. Nếu bạn chỉ cần Claude Code hỏi đáp và sửa vài file nhỏ, dùng Claude Code thuần là đủ và đơn giản hơn. Nếu bạn chỉ muốn thử một vài lệnh, cài lẻ plugin sẽ nhẹ hơn cài toàn bộ. Nếu dự án đang chứa cấu hình .claude/ riêng, hãy sao lưu trước khi chạy init. Còn nếu bạn thường giao việc lớn, nhiều bước, cần bộ nhớ qua các phiên và muốn quan sát agent làm gì, Ruflo là một lựa chọn đáng thử.
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 và sửa mã nguồn tự do. Tuy vậy Ruflo chạy trên Claude Code hoặc Codex, nên chi phí dùng mô hình AI vẫn theo gói của các công cụ đó. README phần đã cung cấp chưa nêu bảng giá riêng cho Ruflo.
Cài Ruflo bằng lệnh nào?
Trong thư mục dự án, chạy `npx ruflo@latest init`, rồi mở lại Claude Code trong cùng thư mục. Nếu bạn không muốn thêm file vào dự án, có thể cài bằng plugin: thêm kho bằng `/plugin marketplace add ruvnet/ruflo` rồi cài `ruflo-core@ruflo`.
Ruflo cần phiên bản Node nào?
File package.json của repo yêu cầu Node từ 20.0.0 trở lên. Nếu dùng đường plugin thì Claude Code cần bản 2.1.287 trở lên, riêng lệnh cài từ terminal cần 2.1.292 trở lên.
Dùng được với Codex hay chỉ có Claude Code?
Dùng được cả hai. Với Codex hoặc client MCP khác, bạn cấu hình command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`. README cũng có lệnh `npx ruflo init --grok` cho Grok Build.
Cài Ruflo có làm thay đổi dự án của tôi không?
Có, nếu dùng `npx ruflo init`: README cho biết lệnh này thêm `.claude/`, `.claude-flow/`, `CLAUDE.md` và các file hỗ trợ vào dự án. Đường cài bằng plugin thì không thêm file nào vào dự án. Bạn nên chạy thử trong nhánh git riêng hoặc thư mục thử nghiệm.
Claude có thể tự làm bậy trong console của Ruflo không?
README mô tả cơ chế giới hạn: bạn chọn mức quyền read, write, manage hoặc full, với chế độ duyệt ask hoặc auto, và mặc định hiện tại là read + ask. Hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận, và có nút Take back control để thu quyền lại. Các mod thì chạy bằng quyền tài khoản của bạn, nên cần đọc code trước khi cài.
Cần GPU hay máy cấu hình mạnh không?
Phần README đã cung cấp chưa nói rõ yêu cầu phần cứng cho đường cài cơ bản. Một số plugin nhắc đến tìm kiếm tăng tốc bằng GPU hoặc chạy mô hình cục bộ, nhưng đó là tuỳ chọn thêm. Bạn nên xem tài liệu của từng plugin trước khi dùng.


