# ruvnet/ruflo: điều phối nhiều AI agent cho Claude Code và Codex — hướng dẫn cài đặt và dùng

> Ruflo (trước đây là Claude Flow) là một agent harness mã nguồn mở, giấy phép MIT. Nó thêm agent, bộ nhớ, hooks và MCP server vào Claude Code hoặc Codex để nhiều agent phối hợp làm việc. Cài chỉ cần một lệnh npx trong thư mục dự án, khá dễ nếu bạn đã có Node.js 20 trở lên.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-06 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-nhieu-ai-agent-claude-code-codex-huong-dan-2

Ruflo là một "agent harness", tức lớp điều phối đặt quanh Claude Code và Codex. Mô hình AI vẫn là bên viết code. Ruflo đưa thêm công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát để AI làm việc có tổ chức hơn. Bạn có thể coi nó là bộ khung giúp nhiều agent chia việc cho nhau thay vì một AI làm một mình.

Repo này hợp với lập trình viên đã dùng Claude Code hoặc Codex và muốn giao việc lớn hơn: rà soát cả repo, viết test, theo dõi chi phí token. Người làm kinh doanh hay văn phòng có thể dùng nếu đã có người dựng sẵn môi trường lập trình. Còn nếu bạn chưa từng dùng Claude Code thì nên làm quen công cụ đó trước.

Đ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 là xong phần chính. Sau đó bạn cứ dùng Claude Code như bình thường, còn hooks lo việc định tuyến tác vụ và ghi nhớ ở phía sau. Hiện repo có khoảng 81.588 sao và 9.608 fork, vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là lớp điều phối bọc quanh Claude Code và Codex: thêm agent chuyên biệt, bộ nhớ qua các phiên, hooks và MCP server chỉ với một lệnh init.
- stars | 82k
- lang | TypeScript
- license | MIT
```

## Ruflo làm được gì

Tư liệu của repo khá dài và nhiều tầng. Mình gom lại thành mấy nhóm dễ hình dung.

**Nhiều agent làm việc như một nhóm (swarm).** Ruflo đi kèm 100+ agent chuyên biệt và cơ chế điều phối. Bạn có thể nhờ "một swarm" rà soát repo thay vì để một AI làm tuần tự. Lợi ích thực tế là việc lớn được chia nhỏ, có agent tìm chỗ rủi ro, có agent viết test.

**Bộ nhớ qua các phiên.** Agent có thể nhớ kinh nghiệm từ các lần làm trước, nhờ cơ sở dữ liệu vector cho bộ nhớ agent. Nhờ vậy bạn đỡ phải giải thích lại cùng một bối cảnh mỗi lần mở Claude Code. README cũng ghi rõ phần học này là mô hình khái niệm, và vẫn cần embedding cùng các module học được cấu hình.

**Hooks tự định tuyến.** README nói bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Sau `init`, hệ thống hooks tự định tuyến tác vụ và học từ các mẫu làm việc thành công.

**Bảng điều khiển (console) ngay cạnh Claude Code.** Bạn xem được workflow, agent, model, token và chi phí. Bạn cũng mở được log và kết quả của từng lần chạy, tìm kiếm, phát lại và so sánh. Mở bằng lệnh `/ruflo` trong Claude Code. Console còn chạy riêng được trong terminal thường.

**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 các mức `read`, `write`, `manage`, `full` và chế độ duyệt `ask` hoặc `auto`. Mặc định hiện 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.** 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í dụ `ruflo-testgen` tìm test còn thiếu và sinh test, `ruflo-cost-tracker` theo dõi token và đặt ngân sách, `ruflo-security-audit` quét lỗ hổng. Bạn chỉ cài cái mình cần.

**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. Đây là tính năng nâng cao, người mới chưa cần đến.

## Cần chuẩn bị gì

Theo tư liệu, bạn cần:

- **Node.js bản 20.0.0 trở lên.** `package.json` của repo yêu cầu như vậy, và lệnh `npx` đi kèm Node.
- **Claude Code** nếu đi đường chính. Riêng cách cài bằng plugin cần Claude Code bản 2.1.287 trở lên. Lệnh cài plugin từ terminal cần bản 2.1.292 trở lên.
- **Hoặc Codex / một MCP client khác**, nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy `init`.

Tư liệu không nói rõ về hệ điều hành, yêu cầu GPU hay API key cho đường cài chính, nên mình không khẳng định gì thêm. Phần mô hình AI vẫn do Claude Code hoặc Codex của bạn cung cấp, với tài khoản và chi phí của chính công cụ đó.

```note
Mod của Ruflo chạy với quyền tài khoản của bạn và không bị đặt trong sandbox. README khuyên đọc code trước khi cài. Hãy để mức Claude control ở read + ask lúc mới thử, rồi mới nâng quyền nếu thật sự cần.
```

## Cài đặt từng bước

```steps
- Kiểm tra Node | Chắc chắn máy có Node.js 20 trở lên
- Chạy init | Gõ npx ruflo@latest init trong thư mục dự án
- Mở lại Claude Code | Mở Claude Code ở đúng thư mục đó để nó nhận agent, hooks, MCP
- Giao việc thử | Đưa một tác vụ thật, ví dụ rà soát repo bằng swarm
- Mở console (tuỳ chọn) | Gõ /ruflo để xem bảng điều khiển
```

### Kiểm tra Node.js

Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) và xem phiên bản Node. Lệnh này là lệnh phổ thông của Node, không nằm trong README của Ruflo:

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 20, bạn cần cập nhật Node trước.

### Chạy init trong thư mục dự án

Đây là bước chính. Bạn phải mở terminal đúng thư mục dự án, vì `init` ghi file vào thư mục hiện tại. Nhiều người mới chạy nhầm ở thư mục khác nên file nằm sai chỗ.

```bash
npx ruflo@latest init
```

Theo README, `init` thêm agent, hooks, bộ nhớ và MCP server của Ruflo vào dự án. Phầ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à settings. Vì thế nếu dự án của bạn đang quản lý bằng git, hãy commit trước khi chạy để dễ xem file nào mới thêm.

Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh:

```bash
npx ruflo@latest init wizard
```

### Mở lại Claude Code

Claude Code nhận các thứ vừa thêm ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code thì hãy đóng rồi mở lại ở cùng thư mục dự án.

### Giao một việc thật

README gợi ý câu lệnh mẫu để dán vào Claude Code:

```text
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 nhờ swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn có thể viết bằng tiếng Việt nếu muốn. Tuy nhiên mình chỉ chắc chắn về câu tiếng Anh đã có trong README.

### Cách khác: chỉ cài plugin trong Claude Code

Nếu bạn không muốn repo bị thêm file, README có đường cài plugin, "zero file trong workspace". Chạy lần lượt trong Claude Code:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo
```

Từ terminal, với Claude Code 2.1.292 trở lên, README ghi lệnh:

```bash
claude plugin install ruflo-core@ruflo --marketplace ruvnet/ruflo
```

Đường này nhẹ hơn nhưng ít tính năng hơn. README nói đường cài plugin chỉ có lệnh slash, vài skill và định nghĩa agent. Bản đầy đủ (98 agent, 60+ lệnh, 30 skill, MCP server, hooks, daemon) nằm ở đường `npx ruflo@latest init`.

### Cách khác: dùng với Codex hoặc MCP client khác

Cấu hình client của bạn với **command** là `npx` và **arguments** là:

```json
["-y", "ruflo@latest", "mcp", "start"]
```

Vị trí điền cấu hình này tuỳ từng client. README chưa hướng dẫn chi tiết cho từng loại, bạn xem tài liệu của client mình đang dùng.

### Cách khác: chạy console trong terminal thường

```bash
npx ruflo tui
```

Thêm `--plain` để in ra một khung hình, tiện cho script.

## Kiểm tra đã chạy được chưa

Tư liệu không đưa ra một lệnh "kiểm tra phiên bản" riêng, nên mình dựa vào những dấu hiệu README có nhắc:

- Sau `init`, thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Mở lại Claude Code, gõ `/ruflo` thì thấy bảng điều khiển.
- Với đường plugin, mở `/plugin` và xem các plugin xuất hiện ở dòng "active mods".
- Trong console, gõ `/ruflo market` sẽ 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 hành động đều hỏi lại bạn trước.

Cách thử chắc nhất là giao câu lệnh swarm mẫu ở trên rồi xem Claude Code có điều phối agent và báo cáo lại không.

## Dùng vào việc thật

Mình dựa vào những gì README mô tả, không thêm tính năng nào ngoài tư liệu.

### Dev nhận một repo lạ và cần biết chỗ nào dễ hỏng

Bạn vừa nhận bàn giao một dự án, chưa biết module nào mong manh. Chạy `npx ruflo@latest init` trong thư mục dự án, mở lại Claude Code, rồi dán câu lệnh mẫu của README:

```text
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 được là: module được cho là rủi ro nhất, các test mới viết cho nó và bản tóm tắt thay đổi. Hãy đọc kỹ test trước khi giữ lại, vì AI có thể viết test chưa sát yêu cầu thật.

> Bạn vẫn viết code như cũ, còn việc phối hợp giữa các agent để Ruflo lo.
>
> — Ông T

### Người dẫn dự án muốn nhìn thấy AI đang làm gì và tốn bao nhiêu

Bạn quản lý một nhóm nhỏ dùng Claude Code và lo chi phí token. Cài `ruflo-console` rồi mở `/ruflo` để xem workflow, agent, model, token và chi phí ở cạnh Claude Code. Nếu cần, cài thêm `ruflo-cost-tracker`, plugin mà README mô tả là theo dõi token, đặt ngân sách và cảnh báo chi phí. Kết quả là bạn có một chỗ nhìn chung thay vì phải mò từng phiên.

### Thử cho Claude tự tạo "mission" trong console, nhưng giữ quyền duyệt

README có một bài thử an toàn. Cài console rồi mở `/ruflo`, chọn **Settings → Claude control → write + ask**. Sau đó nhờ Claude:

```text
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, còn bạn xác nhận hành động tạo trong console. Kết quả: mục Missions có mục tiêu mới, còn Overview ghi lại hành động. README lưu ý rằng tạo mission không có nghĩa tính năng đã được viết xong. Nếu muốn dừng, bạn bấm **Take back control** và các lệnh sau đó của Claude sẽ bị từ chối cho tới khi bạn trao lại quyền.

### Muốn dùng bộ nhớ hoặc kiểm thử riêng lẻ mà không cài cả bộ

Bạn chỉ cần vài chức năng. Dùng đường plugin: thêm marketplace, rồi cài từng plugin, ví dụ:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-rag-memory@ruflo
```

Kết quả là bạn có thêm lệnh slash và định nghĩa agent mà không bị thêm file vào dự án. README cũng nêu rõ `ruflo-core` có MCP server riêng. Tên công cụ của nó có dạng `mcp__plugin_ruflo-core_ruflo__*`, khác với tên công cụ khi cài bằng CLI.

## Lỗi hay gặp và cách xử lý

**Chạy `init` xong mà Claude Code không thấy gì mới.** Claude Code chỉ nhận agent và hooks ở lần khởi động sau. Hãy đóng rồi mở lại ở đúng thư mục đã chạy `init`. Với plugin, gõ `/reload-plugins`.

**Lệnh `npx` báo lỗi hoặc không chạy.** Kiểm tra `node --version`. Repo yêu cầu Node 20.0.0 trở lên. Nếu máy cũ hơn, cập nhật Node rồi chạy lại.

**Lệnh `/plugin` không nhận hoặc cài plugin thất bại.** Cách cài plugin cần Claude Code bản 2.1.287 trở lên, và lệnh terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code. Tư liệu không nói thêm về các lỗi cụ thể khác, nên nếu vẫn lỗi, xem mục tài liệu trong repo.

**Cài trùng một plugin từ hai marketplace.** 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 bật từ cả hai nơi, mod và lệnh sẽ nạp hai lần. Hãy gỡ một bản.

**Claude tự làm quá nhiều trong console.** Quay lại Settings → Claude control và hạ về read + ask, hoặc bấm **Take back control**. Các hành động mạng, chi tiêu và phá huỷ luôn cần xác nhận, nhưng đừng nâng quyền khi chưa hiểu rõ mình đang cho phép gì.

## Có nên dùng không

**Điểm mạnh.** Cài đơn giản bằng một lệnh. Có hai đường cài (đầy đủ hoặc chỉ plugin) nên bạn chọn được mức cam kết. Giấy phép MIT. Repo hoạt động tích cực và có bảng điều khiển để theo dõi agent, token, chi phí. Phần quyền điều khiển có các mức rõ ràng, mặc định thận trọng.

**Giới hạn.** Hệ thống rất lớn: hàng trăm công cụ, hàng chục plugin. Người mới dễ bị ngợp, nên chỉ cần bắt đầu với `init` rồi dùng Claude Code như thường. Một số phần, như học liên tục hay federation, README mô tả ở mức khái niệm hoặc nâng cao. Bản thân README cũng nói các video demo dùng dữ liệu mẫu và không chứng minh việc swarm hay bộ nhớ đã hoàn tất công việc thật. Hãy tự kiểm chứng trên dự án nhỏ trước. Ngoài ra `init` thêm khá nhiều file vào dự án, và mod chạy không có sandbox.

**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ỏ, việc dùng Claude Code thuần là đủ, chưa cần thêm lớp điều phối. Nếu không muốn repo bị thêm file, hãy dùng đường plugin. Nếu bạn không viết code và chưa có ai dựng môi trường, công cụ này chưa phải điểm bắt đầu hợp lý.

## 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. Tư liệu không nói gì về phí của mô hình AI phía sau. Việc dùng Claude Code, Codex hay nhà cung cấp khác vẫn theo tài khoản và gói của bạn. Console có hiển thị token và chi phí để bạn theo dõi.

### Cài Ruflo như thế nào nhanh nhất?

Mở terminal ở thư mục dự án và chạy `npx ruflo@latest init`. Sau đó mở lại Claude Code ở cùng thư mục. Cần Node.js 20 trở lên theo package.json.

### Ruflo có cần GPU không?

Tư liệu cung cấp không nêu yêu cầu GPU cho đường cài chính. Chỉ có một plugin (ruflo-ruvector) được mô tả là tìm kiếm tăng tốc bằng GPU. Phần còn lại chưa có thông tin về phần cứng.

### Chạy được trên Windows không?

Tư liệu không nêu rõ hệ điều hành được hỗ trợ. Lệnh cài chính là `npx` của Node.js, nên điều kiện cần là có Node 20 trở lên. Bạn nên thử trên dự án nhỏ trước khi dùng thật.

### Ruflo khác gì dùng Claude Code thuần?

Ruflo là lớp bọc thêm agent chuyên biệt, bộ nhớ qua các phiên, hooks tự định tuyến, MCP server và bảng điều khiển. Claude Code vẫn là nơi bạn làm việc. Bạn có thể dùng đường plugin nhẹ hoặc đường `init` đầy đủ tuỳ nhu cầu.

### Có dùng được với Codex hoặc công cụ không phải Claude Code không?

Có. README ghi Codex và các MCP client khác dùng được, bằng cách trỏ tới `npx -y ruflo@latest mcp start`. Chi tiết cấu hình từng client chưa có trong tư liệu, bạn xem tài liệu của client đó.

### Cho Claude điều khiển console có nguy hiểm không?

Quyền do bạn đặt: read, write, manage hoặc full, kèm chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask. Hành động mạng, chi tiêu và phá huỷ vẫn cần xác nhận kể cả ở chế độ auto, và bạn có thể bấm Take back control để thu lại quyền.
