# Ruflo: điều phối nhóm agent AI 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: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.

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

Ruflo là một «agent harness» mã nguồn mở: lớp công cụ bao quanh Claude Code và Codex để các agent AI không chỉ chạy một mình mà biết chia việc, nhớ lại kinh nghiệm và phối hợp với nhau. Repo này vốn tên là Claude Flow, do Reuven Cohen (rUv) tạo ra, viết chủ yếu bằng TypeScript, giấy phép MIT. Hiện có khoảng 81.600 sao và khoảng 9.600 fork trên GitHub.

Cách hiểu đơn giản nhất theo chính README: Agent = Model + Harness. Model (như Claude) là bộ não biết viết code. Harness là cái bàn làm việc xung quanh: công cụ, bộ nhớ, vòng lặp, giới hạn an toàn. Ruflo là phần bàn làm việc đó. Sau khi cài, Claude Code của bạn có thêm hàng chục agent chuyên biệt, hook tự động điều hướng tác vụ, và một MCP server để dùng các công cụ của Ruflo.

Bạn nên đọc bài này nếu bạn là lập trình viên (kể cả mới) đang dùng Claude Code hoặc Codex và muốn giao các việc lớn hơn như rà soát cả repo, viết test, ghi nhớ giữa các phiên. Điểm đáng giá nhất: chỉ một lệnh `npx ruflo@latest init` là xong phần cài, và README khuyên bạn cứ dùng Claude Code bình thường, không cần học hết hàng trăm công cụ.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung bao quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, swarm phối hợp và MCP server chỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README giới thiệu rất nhiều thứ. Mình chọn những ý bạn dễ thấy lợi ích nhất.

- **Agent chuyên biệt và swarm.** Bạn có hơn 100 agent chuyên biệt (README ghi 98 agent ở đường cài bằng CLI). Chúng tự tổ chức thành «swarm», tức một nhóm cùng làm một việc. Lợi ích: một yêu cầu lớn được chia nhỏ thay vì dồn hết cho một cuộc hội thoại.
- **Bộ nhớ qua các phiên.** Agent nhớ được kinh nghiệm từ lần làm trước. README có nhắc bộ nhớ vector, tìm kiếm cục bộ và học từ tác vụ thành công. Lợi ích: bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code.
- **Hook tự động.** Sau `init`, hệ thống hook tự định tuyến tác vụ và phối hợp agent ở phía sau. Bạn không phải gõ lệnh riêng cho từng việc.
- **MCP server.** Codex hoặc bất kỳ client MCP nào cũng nối được vào Ruflo, không chỉ riêng Claude Code.
- **Bảng điều khiển (console).** Một «buồng lái» đặt cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí; mở log từng lần chạy, tìm kiếm, xem lại và so sánh. Chạy được cả trong terminal thường với `npx ruflo tui`.
- **Cho Claude điều khiển console, nhưng bạn đặt giới hạn.** Có bốn mức quyền: `read`, `write`, `manage`, `full`, kèm 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á hủy luôn cần bạn xác nhận, kể cả ở chế độ `auto`.
- **Kho plugin.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài): swarm, tạo test, quét bảo mật, theo dõi chi phí token, tìm kiếm RAG, tài liệu, v.v. Bạn cài cái nào cần.
- **Federation.** Agent trên các máy khác nhau có thể trao đổi với nhau một cách an toàn. Với người mới, phần này chưa cần đụng tới.

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

Tư liệu của repo chỉ nêu một số yêu cầu rõ ràng:

- **Node.js từ 20.0.0 trở lên.** `package.json` yêu cầu như vậy, và lệnh cài dùng `npx` đi kèm Node.
- **Claude Code** nếu bạn dùng theo cách chính. Riêng đường cài chỉ bằng plugin, README yêu cầu Claude Code **2.1.287 trở lên**; lệnh cài plugin từ terminal cần **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy `init` trong đó.
- **Codex hoặc client MCP khác** là tuỳ chọn, nếu bạn không dùng Claude Code.

README phần mình có không nói rõ về hệ điều hành, phần cứng hay API key riêng cho Ruflo. Vì vậy mình không khẳng định gì thêm. Bạn dùng Claude Code hoặc Codex thì cần tài khoản của chúng như bình thường. Nếu bạn dùng Windows, hãy xem thêm mục tài liệu trong thư mục `docs/` của repo.

```note
Các mod của Ruflo chạy với quyền của tài khoản bạn và không bị cô lập (sandbox). README dặn rõ: hãy đọc mã nguồn trước khi cài. Hãy để chế độ Claude control ở mức read + ask khi mới thử.
```

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

README có nhiều đường cài. Mình hướng dẫn đường chính (CLI) trước, rồi nói các đường phụ.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án bạn muốn dùng Ruflo
- Chạy init | Chạy một lệnh npx để thêm agent, hook, bộ nhớ, MCP server
- Mở 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 tác vụ | Dán câu lệnh mẫu để Ruflo điều phối swarm
- Mở console | Gõ /ruflo trong Claude Code để xem bảng điều khiển
```

### Mở terminal trong thư mục dự án

Điểm người mới hay vấp là chạy lệnh sai chỗ. `init` thêm file vào thư mục hiện tại, nên bạn phải mở terminal đúng thư mục dự án của mình. Nếu chưa có dự án thử, bạn có thể tạo một thư mục trống để làm quen.

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

Đổi `duong-dan-toi-du-an-cua-ban` thành đường dẫn thật trên máy bạn.

### Chạy lệnh init

Đây là lệnh chính trong README:

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

`npx` tải và chạy bản Ruflo mới nhất mà không cần cài toàn cục. 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ứ như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings trong thư mục làm việc. Nếu dự án của bạn đã có `CLAUDE.md`, hãy sao lưu hoặc dùng git để xem lại thay đổi.

Muốn cấu hình tương tác từng bước, README có lệnh:

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

### Mở lại Claude Code và giao tác vụ đầu tiên

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thứ mới ở lần khởi động kế tiếp, nên nếu nó đang mở sẵn, hãy thoát rồi mở lại. Sau đó thử 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.
```

### Đường phụ: chỉ cài plugin trong Claude Code

Đường này không thêm file nào vào dự án và 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
```

Nếu dùng Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal thường:

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

README nhắc: đường plugin là bản «nhẹ», chỉ có lệnh gạch chéo và vài skill. Muốn trọn vẹn (agent, hook, daemon, MCP server) thì dùng `npx ruflo@latest init`.

### Đường phụ: Codex hoặc client MCP khác

Không cần thiết lập dự án. Bạn cấu hình client với **command** là `npx` và **arguments** là:

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

Cách điền cụ thể tuỳ từng client, nên bạn xem tài liệu của client đó để biết điền vào đâu.

### Đường phụ: chạy console trong terminal thường

```bash
npx ruflo tui
```

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

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

Theo README, có vài dấu hiệu để bạn biết đã ổn:

- Sau `init` và khởi động lại Claude Code, thư mục dự án có các thư mục như `.claude/` và `.claude-flow/` cùng file `CLAUDE.md`.
- Trong Claude Code, gõ `/ruflo` thì console mở ra (nếu bạn đã cài `ruflo-console`).
- Nếu cài bằng plugin, gõ `/plugin` và kiểm tra các mod xuất hiện ở dòng «active mods».
- Chạy `npx ruflo tui` thì giao diện console hiện trong terminal.

Tuyệt chiêu nhỏ: hãy giao một việc nhỏ, dễ kiểm chứng (ví dụ ở phần sau) thay vì việc lớn. Nếu Claude Code phản hồi và console ghi nhận hành động, bạn đã cài thành công.

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

README mô tả công cụ khá rộng, nên mình chỉ chọn các tình huống bám sát những gì tư liệu nói.

### Rà soát một dự án vừa nhận bàn giao

Bạn là lập trình viên mới nhận lại một dự án cũ, chưa biết chỗ nào dễ hỏng. Sau khi `init` và mở lại Claude Code, bạn dán đúng 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ả mong đợi: Claude Code điều phối nhóm agent để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn nên đọc kỹ phần tóm tắt và chạy lại test trước khi giữ thay đổi.

> Đừng cố học hết hàng trăm công cụ, hãy cài một lệnh rồi giao cho nó một việc thật.
>
> — Ông T

### Tạo một «mission» và giữ quyền kiểm soát

Bạn muốn thử cho Claude thao tác trên console nhưng vẫn yên tâm. README có một kịch bản năm bước. Cài console, gõ `/ruflo`, vào **Settings → Claude control** và chọn **write + ask**. Rồi nhờ Claude:

```text
Create a mission to add a dark mode toggle. Show me the mission and its status.
```

Claude mở trang Missions và đặt mục tiêu; bạn xác nhận hành động tạo đang chờ. Kết quả: mục Missions có mục tiêu mới và Overview ghi lại hành động. README lưu ý rõ: tạo mission không có nghĩa tính năng đã được làm xong. Muốn dừng, bấm **Take back control**; lệnh gọi sau đó của Claude sẽ bị từ chối cho đến khi bạn trả quyền lại.

### Dùng Ruflo từ Codex hoặc công cụ MCP khác

Bạn đang dùng Codex hoặc một ứng dụng hỗ trợ MCP chứ không phải Claude Code. Bạn khai báo một MCP server với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]` như phần cài đặt ở trên. Kết quả: client của bạn gọi được các công cụ MCP của Ruflo (README nói có 406 công cụ MCP, nhưng bạn không cần dùng hết).

### Thêm plugin cho đúng nhu cầu

Bạn là dev làm việc nhóm và chỉ cần vài thứ. Ví dụ muốn theo dõi chi phí token thì có `ruflo-cost-tracker`; muốn tìm kiếm trong bộ nhớ thì có `ruflo-rag-memory`; muốn sinh test thì có `ruflo-testgen`. Cài từng cái bằng cú pháp của README:

```text
/plugin install ruflo-cost-tracker@ruflo
```

Rồi gõ `/ruflo market` trong console để xem Plugin Catalog, nơi có nút cài, bật, tắt, cập nhật (mỗi thao tác đều hỏi lại bạn trước).

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

**Chạy lệnh nhưng Claude Code không thấy gì mới.** Thường do bạn chưa khởi động lại Claude Code hoặc mở nó ở thư mục khác. Hãy thoát, mở lại ngay trong thư mục đã chạy `init`. Với plugin, chạy `/reload-plugins`.

**Lệnh `/plugin` hoặc `claude plugin install` báo không nhận.** README yêu cầu Claude Code 2.1.287 trở lên cho đường plugin, và 2.1.292 trở lên cho lệnh cài từ terminal. Hãy cập nhật Claude Code trước.

**Báo lỗi phiên bản Node.** `package.json` yêu cầu Node 20.0.0 trở lên. Kiểm tra bằng `node --version`, rồi nâng cấp nếu thấp hơn.

**Cài hai lần cù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 không mod và lệnh sẽ tải hai lần. Chọn một nguồn rồi gỡ nguồn còn lại.

**Tên công cụ MCP không khớp tài liệu.** README giải thích plugin `ruflo-core` đăng ký MCP server riêng, nên công cụ có tên dạng `mcp__plugin_ruflo-core_ruflo__*`, khác tên ngắn của đường CLI. Muốn đúng tên theo tài liệu CLI, hãy dùng `npx ruflo@latest init`.

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

**Điểm mạnh.** Cài nhanh (một lệnh), giấy phép MIT, repo còn được cập nhật trong 3 tháng gần đây. Phạm vi rất rộng: agent, bộ nhớ, console, plugin, hỗ trợ cả Claude Code lẫn Codex và client MCP. Cơ chế quyền (read, write, manage, full cùng ask hoặc auto) cho bạn giữ quyền quyết định.

**Giới hạn.** Hệ thống lớn, nhiều khái niệm (swarm, federation, mod, plugin), người mới dễ choáng. Đường cài đầy đủ thêm nhiều file vào dự án, nên cần xem lại thay đổi. README tự nhận một số phần là «mô hình khái niệm», và các đoạn demo dùng dữ liệu mẫu, không phải bằng chứng cho việc swarm đã hoàn thành công việc thật. Bạn nên tự kiểm chứng kết quả. Các mod chạy không sandbox, nên cần đọc mã trước khi cài. README cũng không nói về chi phí gọi mô hình, nên bạn cần tự theo dõi token (có plugin cost-tracker cho việc này).

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code làm việc nhỏ lẻ, dùng Claude Code thuần là đủ và gọn hơn. Nếu bạn muốn thử nhẹ, hãy cài từng plugin qua `/plugin` thay vì chạy `init`. Còn nếu bạn muốn thử nghiệm làm việc nhiều agent, có bộ nhớ và giám sát, Ruflo là một lựa chọn đáng thử, nhất là khi bạn bắt đầu từ một dự án nhỏ.

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

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

Mã nguồn Ruflo dùng giấy phép MIT và cài bằng npx. Tuy vậy Ruflo bao quanh Claude Code và Codex, nên chi phí dùng các dịch vụ đó vẫn tính theo tài khoản của bạn. Tư liệu không nêu bảng giá riêng, và có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

### Cài Ruflo có khó không?

Đường 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. Bạn cũng có thể cài chỉ qua plugin bằng các lệnh `/plugin` nếu không muốn thêm file vào dự án.

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

Theo README, Ruflo là lớp bao quanh Claude Code và Codex, thêm agent chuyên biệt, hook tự định tuyến, bộ nhớ qua các phiên, console theo dõi và MCP server. Claude Code thuần không có sẵn các phần đó. Với việc nhỏ lẻ, Claude Code thuần có thể là đủ.

### Ruflo có dùng được với Codex hoặc công cụ khác 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"]`. Cách điền cụ thể tuỳ từng client, tư liệu không hướng dẫn chi tiết.

### Cần GPU hay cấu hình máy mạnh không?

Tư liệu mà mình có không nêu yêu cầu GPU hay cấu hình phần cứng cho đường cài chính. README chỉ nói rõ Node 20 trở lên và phiên bản Claude Code tối thiểu cho đường plugin. Một vài plugin riêng như ruflo-ruvector có nhắc tìm kiếm tăng tốc GPU, nhưng đây là tuỳ chọn.

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

README phần tư liệu mình có không nói rõ về hệ điều hành. Ruflo chạy qua Node và npx, nên bạn có thể thử, nhưng chưa có thông tin xác nhận cụ thể. Bạn nên xem thư mục docs trong repo hoặc phần Issues nếu gặp vấn đề.

### Ruflo có an toàn khi cho Claude điều khiển không?

README cho biết mặc định là read + ask, và các hành động vượt quyền sẽ bị từ chối. Hành động liên quan mạng, chi tiêu, phá hủy vẫn cần xác nhận kể cả ở chế độ auto, và bạn có nút Take back control. Tuy nhiên các mod chạy với quyền tài khoản của bạn và không sandbox, nên cần đọc mã trước khi cài.
