# 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ở bằng TypeScript, giấy phép MIT. Nó bọc quanh Claude Code và Codex để thêm nhiều agent chuyên biệt, nhóm agent làm việc phối hợp (swarm), bộ nhớ dài hạn và máy chủ MCP. Cài khá dễ: chạy một lệnh npx trong thư mục dự án, cần Node 20 trở lên.

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

Ruflo là một “agent harness”: lớp công cụ bao quanh Claude Code và Codex để AI không chỉ trả lời từng câu mà còn làm việc có tổ chức. Nói cách khác, mô hình AI là người viết, còn Ruflo là cái bàn làm việc: nó đưa thêm công cụ, bộ nhớ, vòng lặp kiểm tra và các giới hạn an toàn. Dự án trước đây tên là Claude Flow, do Reuven Cohen (rUv) tạo ra.

Nếu bạn đã dùng Claude Code và thấy mỗi phiên làm việc đều bắt đầu lại từ đầu, hoặc muốn giao một việc lớn cho nhiều “nhân viên AI” cùng làm, Ruflo đáng thử. Repo hiện có khoảng 81.600 sao và khoảng 9.600 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à độ dễ cài: một lệnh `npx ruflo@latest init` trong thư mục dự án là đủ để Claude Code nhận thêm agent, hooks, bộ nhớ và MCP server. Sau đó bạn cứ dùng Claude Code như bình thường, phần điều phối chạy ngầm.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là lớp điều phối (harness) bao quanh Claude Code và Codex, thêm agent, bộ nhớ, hooks và MCP server chỉ bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Theo README, sau khi `init` bạn không cần học hết hàng trăm công cụ. Dưới đây là những phần bạn sẽ thấy lợi ích rõ nhất.

### Nhiều agent làm việc như một nhóm

Ruflo cung cấp nhiều agent chuyên biệt và cách phối hợp chúng thành “swarm” (đàn agent). Bạn giao một việc lớn, ví dụ rà soát cả repo, và các agent chia nhau làm thay vì một AI ôm hết. Lợi ích thực tế: việc dài và nhiều bước đỡ bị rối.

### Bộ nhớ qua nhiều phiên

Ruflo có bộ nhớ để agent nhớ lại kinh nghiệm giữa các phiên làm việc, kèm các plugin như `ruflo-agentdb` (cơ sở dữ liệu vector cho bộ nhớ agent) và `ruflo-rag-memory` (tìm kiếm thông minh). README nói rõ phần học tập là “mô hình khái niệm”: truy xuất vector cục bộ có thể chạy không cần LLM, nhưng vẫn cần embedding và các mô-đun học đã được cấu hình.

### Hooks tự định tuyến công việc

Sau `init`, hệ thống hooks tự phân loại tác vụ, học từ các mẫu làm thành công và điều phối agent ở nền. Bạn không phải gọi tay từng công cụ.

### Bảng điều khiển ngay cạnh Claude Code

Plugin `ruflo-console` là một “buồng lái”: theo dõi workflow, agent, mô hình, token và chi phí. Bạn mở bằng lệnh `/ruflo`. Bạn cũng có thể cho Claude điều khiển bảng này, nhưng với các mức quyền do bạn chọn (`read`, `write`, `manage`, `full`). Mặc định là đọc và hỏi lại trước khi làm. Các thao tác liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận.

### Hệ plugin lớn

Marketplace của Ruflo có 48 plugin: điều phối (`ruflo-swarm`, `ruflo-autopilot`), bộ nhớ, sinh test (`ruflo-testgen`), quét bảo mật (`ruflo-security-audit`), theo dõi chi phí (`ruflo-cost-tracker`), tài liệu (`ruflo-docs`) và nhiều loại khác. Bạn chỉ cài cái mình cần.

### Chạy được với Codex và client MCP khác

Không chỉ Claude Code: Codex hoặc bất kỳ client MCP nào cũng trỏ được vào máy chủ MCP của Ruflo.

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

- **Node.js từ phiên bản 20 trở lên.** Đây là yêu cầu trong `package.json` của repo.
- **Một thư mục dự án** để chạy lệnh. README dặn chạy trong thư mục dự án của bạn.
- **Claude Code** nếu bạn dùng đường cài chính. Riêng đường cài bằng plugin cần Claude Code phiên bản 2.1.287 trở lên (lệnh cài từ terminal cần 2.1.292 trở lên).
- **Codex hoặc client MCP khác** nếu bạn không dùng Claude Code.

Tư liệu không nói rõ về hệ điều hành, phần cứng hay API key bắt buộc. Vì vậy mình không khẳng định gì thêm ở các điểm này; bạn nên xem phần tài liệu trong thư mục `docs/` của repo nếu cần.

```note
Mods (plugin chạy trong tiến trình Claude Code) chạy với quyền của tài khoản bạn và không bị đóng khung trong sandbox. README khuyên đọc mã của mod trước khi cài. Ngoài ra, agent chạy tự động có thể tiêu tốn token và chi phí: hãy xem bảng điều khiển hoặc plugin theo dõi chi phí khi giao việc lớn.
```

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

Ruflo có nhiều đường cài. Đường chính (đầy đủ nhất) là chạy `init` trong thư mục dự án. Đường nhẹ hơn là cài plugin trong Claude Code, không thêm file nào vào dự án.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án của bạn
- Chạy init | Dùng npx ruflo@latest init để thêm agent, hooks, bộ nhớ và MCP server
- Khởi động lại Claude Code | Mở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc | Đưa cho Claude Code một tác vụ thật dùng swarm
- (Tuỳ chọn) Cài plugin hoặc dùng Codex | Thêm bảng điều khiển hoặc nối client MCP khác
```

### Mở terminal đúng thư mục dự án

Đây là 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 trong thư mục dự án trước khi chạy. Ví dụ với Windows PowerShell hoặc macOS/Linux:

```bash
cd duong-dan-toi-du-an-cua-ban
```

Hãy thay `duong-dan-toi-du-an-cua-ban` bằng đường dẫn thật. Bạn cũng cần Node 20 trở lên; kiểm tra bằng `node --version`.

### Chạy lệnh init

Lệnh trong README:

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

`npx` tải và chạy gói `ruflo` bản mới nhất mà không cần cài toàn cục. `init` sẽ thêm agent, hooks, bộ nhớ và MCP server vào dự án. Theo bảng so sánh trong README, đường này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng các file hỗ trợ và cài đặt. Vì vậy nếu dự án dùng Git, bạn nên commit trạng thái hiện tại trước để dễ xem Ruflo thêm gì.

Muốn thiết lập theo kiểu hỏi đáp, README có lệnh:

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

### Khởi động lại Claude Code và giao việc

Mở Claude Code trong đú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 từ trước, hãy thoát và mở lại.

Sau đó thử một việc thật, ví dụ câu mẫu trong README:

```text
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 bằng tiếng Việt, nhưng nhớ nhắc rõ là dùng swarm của Ruflo.

### 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, phù hợp nếu bạn muốn thử nhẹ. Cần Claude Code 2.1.287 trở lên. Gõ các lệnh sau bên 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
```

Các lệnh này thêm marketplace của Ruflo, cài lõi, bảng điều khiển và mods, nạp lại plugin rồi mở bảng `/ruflo`. Nếu cần thêm swarm hoặc bộ nhớ RAG, README liệt kê `ruflo-swarm@ruflo` và `ruflo-rag-memory@ruflo` cùng cách cài tương tự.

Từ terminal thường (Claude Code 2.1.292 trở lên), README ghi lệnh:

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

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

Không cần cài dự án. Trong phần cấu hình MCP của client, đặt **command** là `npx` và **arguments** là:

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

Tương đương chạy `npx -y ruflo@latest mcp start`. Cách điền cụ thể phụ thuộc client bạn dùng, README không hướng dẫn riêng từng client.

### Chạy bảng điều khiển trong terminal thường

Bảng điều khiển có thể chạy riêng, không cần Claude Code:

```bash
npx ruflo tui
```

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

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

Sau khi `init` xong và khởi động lại Claude Code, bạn có thể kiểm tra theo tư liệu như sau:

1. **Thấy file mới trong dự án.** Với đường `init`, thư mục có `.claude/`, `.claude-flow/` và `CLAUDE.md`.
2. **Mở được bảng điều khiển.** Trong Claude Code gõ `/ruflo`. Nếu cài đường plugin, gõ `/plugin` để xem Ruflo có xuất hiện trong dòng mods đang hoạt động hay không.
3. **Giao một việc nhỏ.** Dùng câu mẫu ở trên và xem Claude Code có điều phối agent không. Nếu bạn mở bảng điều khiển, các agent và workflow sẽ hiện ở đó.

Một bài kiểm tra an toàn trong README: bật **Settings → Claude control → write + ask**, rồi nhờ Claude “Create a mission to add a dark mode toggle. Show me the mission and its status.” Bạn xác nhận hành động tạo, rồi kiểm tra mục Missions có mục tiêu đó và Overview 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.

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

Phần dưới là các tình huống mình đề xuất dựa trên khả năng đã ghi trong README. Kết quả thực tế còn phụ thuộc dự án và mô hình bạn dùng.

### Dev mới rà soát một repo lạ

Bạn vừa nhận một dự án cũ, không ai ghi chú. Chạy `npx ruflo@latest init` trong thư mục đó, mở lại Claude Code rồi gõ đúng câu 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.
```

Bạn nhận lại phần tóm tắt về module rủi ro nhất, các bài test được viết thêm và danh sách thay đổi. Hãy đọc kỹ rồi tự chạy test trước khi tin kết quả.

> Agent = Model + Harness. Mô hình viết, còn harness cho nó công cụ, bộ nhớ và giới hạn để làm việc thật.
>
> — Ông T

### Nhân viên văn phòng muốn quan sát AI đang làm gì

Bạn không muốn giao việc rồi ngồi chờ mù. Cài ba plugin `ruflo-core`, `ruflo-console`, `ruflo-mods` như phần trên, rồi gõ `/ruflo`. Bảng điều khiển cho bạn thấy workflow, agent, token và chi phí cạnh Claude Code. Nếu có việc lỗi, bạn mở log và kết quả của agent để xem chuyện gì xảy ra. Kết quả: bạn kiểm soát được tiến độ và chi phí thay vì đoán.

### Chủ doanh nghiệp nhỏ muốn giữ ngữ cảnh qua nhiều ngày

Bạn nhờ AI hỗ trợ một dự án website trong nhiều tuần và mệt vì phải giải thích lại từ đầu. Với `init`, Ruflo có bộ nhớ qua các phiên. Bạn có thể thêm `ruflo-rag-memory@ruflo` để tìm kiếm bộ nhớ thông minh hơn. Kết quả mong đợi: các phiên sau tận dụng được kinh nghiệm của phiên trước. Chất lượng bộ nhớ phụ thuộc cấu hình embedding, nên hãy thử trên một việc nhỏ trước.

### Dùng Codex hoặc client MCP khác

Bạn dùng Codex thay vì Claude Code. Thêm máy chủ MCP của Ruflo với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Client của bạn sẽ gọi được công cụ Ruflo qua MCP mà không cần đổi cấu trúc dự án. Kết quả: dùng chung một bộ công cụ điều phối cho nhiều trợ lý AI.

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

### Lệnh npx báo lỗi hoặc không chạy

Thường do Node cũ hoặc chưa cài. Gõ `node --version` và đảm bảo từ 20 trở lên. Nếu thấp hơn, hãy cập nhật Node rồi chạy lại.

### Claude Code không thấy agent hoặc lệnh /ruflo

Claude Code chỉ nhận cấu hình ở lần khởi động kế tiếp. Hãy thoát và mở lại trong đúng thư mục đã chạy `init`. Với đường plugin, chạy `/reload-plugins` và kiểm tra `/plugin`. Nếu vẫn không thấy, kiểm tra phiên bản Claude Code: README yêu cầu từ 2.1.287 trở lên cho đường plugin.

### Chạy init nhầm thư mục, dự án bị thêm file lạ

`init` ghi file vào thư mục hiện tại. Nếu bạn dùng Git, hãy commit trước khi chạy để dễ xem hoặc huỷ phần thêm vào. Với Grok, README có tuỳ chọn `--dry-run` để xem trước. Tuỳ chọn này được ghi trong ngữ cảnh `npx ruflo init --grok`; với các trường hợp khác, bạn nên kiểm tra trong tài liệu.

### Cài một plugin từ hai marketplace

README cảnh báo vài plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow` nên chỉ cài từ một marketplace. Cài từ cả hai thì mod và lệnh bị nạp hai lần. Hãy gỡ bản thừa.

### Chi phí hoặc quyền vượt ý muốn

Swarm chạy nhiều agent nên có thể dùng nhiều token. Để an toàn, giữ chế độ điều khiển mặc định là đọc và hỏi lại, chỉ nâng quyền khi thật cần. Theo dõi bằng bảng điều khiển hoặc plugin `ruflo-cost-tracker`. Có nút **Take back control** để ngắt quyền điều khiển của Claude khi cần.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Hỗ trợ cả Claude Code lẫn Codex. Hệ plugin rộng, có bảng điều khiển trực quan và cơ chế quyền rõ ràng. Giấy phép MIT, repo có cộng đồng lớn và vẫn cập nhật.

**Giới hạn.** Số lượng khái niệm rất nhiều (README nhắc 406 công cụ MCP, 61 lệnh CLI), người mới dễ choáng. Một số phần như học tập và bộ nhớ chỉ là mô hình khái niệm và còn phụ thuộc cấu hình. README cũng nói rõ các bản demo dùng dữ liệu mẫu, không chứng minh swarm đã hoàn thành việc thật. Và `init` thêm khá nhiều file vào dự án.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần Claude Code làm việc nhỏ, cứ dùng nguyên bản là đủ. Nếu muốn thử nhẹ, hãy cài đường plugin (không thêm file). Chỉ dùng `init` khi bạn đã sẵn sàng cho phần điều phối đầy đủ.

Gợi ý của mình: thử trên một dự án nhỏ hoặc bản sao trước, giữ quyền ở mức đọc và hỏi lại, rồi mở rộng dần khi bạn đã hiểu nó làm gì.

## Câu hỏi thường gặp

### Ruflo có miễn phí không?

Bản thân repo dùng giấy phép MIT nên mã nguồn dùng tự do. Tuy nhiên Ruflo điều phối các mô hình AI như Claude Code hay Codex, và chi phí của các dịch vụ đó thuộc tài khoản của bạn. Tư liệu không nêu bảng giá riêng cho Ruflo.

### Ruflo cần phiên bản Node nào?

File package.json của repo yêu cầu Node 20.0.0 trở lên. Bạn kiểm tra bằng lệnh node --version trước khi chạy npx.

### Cài Ruflo bằng lệnh nào?

Mở terminal trong thư mục dự án và chạy npx ruflo@latest init, sau đó mở lại Claude Code trong cùng thư mục. Nếu không muốn thêm file vào dự án, bạn có thể cài plugin từ bên trong Claude Code bằng /plugin marketplace add ruvnet/ruflo rồi /plugin install ruflo-core@ruflo.

### Ruflo 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 client MCP khác dùng được: cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. README cũng nhắc đến tuỳ chọn cho Grok; chi tiết từng công cụ bạn nên xem trong tài liệu của repo.

### Ruflo khác gì dùng Claude Code thông thường?

Claude Code là công cụ chính để viết mã, còn Ruflo là lớp bao quanh, thêm nhiều agent chuyên biệt, nhóm agent phối hợp, bộ nhớ qua các phiên, hooks và bảng điều khiển. Sau khi init, bạn vẫn dùng Claude Code như bình thường và phần điều phối chạy ngầm.

### Cài plugin có an toàn không?

README cảnh báo các mods chạy với quyền của tài khoản bạn và không nằm trong sandbox, nên cần đọc mã trước khi cài. Chế độ điều khiển mặc định là đọc và hỏi lại, các hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận. Tư liệu chưa có thông tin chi tiết hơn về cách dữ liệu được xử lý.

### Chạy Ruflo có cần GPU không?

Tư liệu được cung cấp không nói Ruflo bắt buộc GPU hay yêu cầu phần cứng cụ thể. README chỉ nhắc đến một plugin tìm kiếm có hỗ trợ GPU là tuỳ chọn. Hệ điều hành được hỗ trợ cũng chưa được nêu rõ, bạn nên xem tài liệu trong repo.
