# ruflo: điều phối nhóm 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: lớp công cụ bao quanh Claude Code hoặc Codex để chia việc cho nhiều agent, nhớ ngữ cảnh giữa các phiên và có kiểm soát quyền hạn. Bạn dùng nó để giao những việc lớn như rà soát cả repo, viết test, theo dõi chi phí. Cài khá dễ: chỉ cần Node 20 trở lên và chạy một lệnh npx trong thư mục dự án.

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

Ruflo là một “agent harness”: lớp công cụ đặt quanh Claude Code và Codex để các AI agent làm việc có tổ chức hơn. Model lo phần viết code và suy nghĩ. Ruflo lo phần còn lại: công cụ, bộ nhớ, vòng lặp, giới hạn quyền, và việc chia việc cho nhiều agent cùng làm. Repo này trước đây có tên Claude Flow.

Nếu bạn đã dùng Claude Code và thấy nó làm tốt từng việc nhỏ nhưng khó giữ mạch với việc lớn, Ruflo dành cho bạn. Một lệnh `init` trong thư mục dự án sẽ thêm agent, hook, 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 bên dưới.

Điểm đáng giá nhất là bạn không phải học hết hệ thống. README nói thẳng: không cần nhớ hàng trăm công cụ MCP hay hàng chục lệnh CLI. Cài xong, giao việc thật cho Claude Code là bắt đầu được. Repo hiện có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, viết chủ yếu bằng TypeScript, và vẫn được cập nhật trong vài tháng gần đây.

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

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

Ruflo là bộ công cụ khá lớn. Dưới đây là những phần mà người mới dễ thấy giá trị nhất.

**Nhiều agent làm việc như một nhóm (swarm).** Thay vì một agent làm tất cả, Ruflo chia việc cho nhiều agent chuyên biệt. README nói bản cài bằng CLI có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: bạn giao một mục tiêu lớn như “rà soát repo, viết test, tóm tắt thay đổi”, nhóm agent tự chia nhau làm.

**Bộ nhớ qua nhiều phiên.** Agent có thể nhớ kinh nghiệm từ các việc trước và dùng lại. README mô tả đây là bộ nhớ vector, có plugin riêng cho lưu và khôi phục bộ nhớ giữa các phiên. 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ự định tuyến việc.** Sau `init`, hệ thống hook tự chọn cách xử lý và học từ các mẫu làm thành công. Bạn không phải gõ lệnh đặc biệt.

**Bảng điều khiển (console) cạnh Claude Code.** Console cho bạn theo dõi workflow, agent, model, token và chi phí. Bạn cũng có thể mở nhật ký, tìm kiếm, xem lại và so sánh các lần chạy. Gõ `/ruflo` trong Claude Code để mở.

**Để Claude lái console, bạn đặt giới hạn.** Mục Settings → Claude control 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. Hành động tốn tiền, đụng mạng hoặc phá hủy vẫn phải bạn xác nhận, kể cả khi để `auto`. Có nút “Take back control” để lấy lại quyền ngay.

**Hệ plugin lớn.** README liệt kê 48 plugin, 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 chỗ thiếu test và tạo test, `ruflo-cost-tracker` theo dõi token và đặt ngân sách, `ruflo-aidefence` chặn prompt injection và phát hiện dữ liệu cá nhân.

**Làm việc được với Codex và client MCP khác.** Ngoài Claude Code, bạn có thể trỏ Codex hoặc một client MCP bất kỳ vào máy chủ MCP của Ruflo.

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

Tư liệu repo nói khá ít về yêu cầu, nên mình chỉ ghi những gì có:

- **Node.js 20 trở lên.** `package.json` của repo yêu cầu `>=20.0.0`. Bạn cần có `npx` đi kèm Node.
- **Claude Code hoặc Codex** (hoặc một client MCP khác) để dùng cùng Ruflo.
- **Claude Code 2.1.287 trở lên** nếu bạn chọn cách cài bằng plugin. Lệnh cài từ terminal cần bản 2.1.292 trở lên.
- **Một thư mục dự án** để chạy `init`.

README chưa nêu yêu cầu cụ thể về hệ điều hành, RAM hay GPU. Cần biết chắc thì bạn xem file README.md và thư mục docs trong repo.

```note
Ruflo dùng cùng Claude Code hoặc Codex của bạn, nên chi phí token vẫn theo tài khoản của bạn ở các công cụ đó. Hãy thử với việc nhỏ trước, và dùng console hoặc plugin theo dõi chi phí để xem mức tiêu thụ.
```

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

Ruflo có hai đường cài khác nhau. Đường CLI (`npx ruflo init`) cho đầy đủ tính năng và là đường README khuyến nghị cho dùng thật. Đường plugin nhẹ hơn, không thêm file vào dự án.

```steps
- Kiểm tra Node | Chắc chắn máy có Node 20 trở lên
- Mở terminal đúng chỗ | Vào thư mục dự án bạn muốn dùng
- Chạy init | Một lệnh npx thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude Code | Mở trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc | Dán câu lệnh mẫu và xem kết quả
```

### Kiểm tra Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và chạy:

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 20, bạn cần cập nhật Node trước. Nếu báo không tìm thấy lệnh, bạn chưa cài Node.

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

Đây là chỗ người mới hay vấp nhất. Lệnh `init` thêm file vào thư mục hiện tại, nên bạn phải đứng đúng trong thư mục dự án. Ví dụ:

```bash
cd duong-dan-toi-thu-muc-du-an
```

Thay `duong-dan-toi-thu-muc-du-an` bằng đường dẫn thật trên máy bạn. Bạn không cần clone repo ruflo về để dùng cách này.

### Chạy init

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

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

`npx` tải và chạy Ruflo mà không cần cài toàn cục. Lệnh thêm agent, hook, bộ nhớ và MCP server vào dự án. README cho biết bản cài này tạo các thư mục `.claude/`, `.claude-flow/`, file `CLAUDE.md`, các file hỗ trợ và cài đặt trong dự án. Nếu dự án đã có `CLAUDE.md` của bạn, nên sao lưu hoặc dùng git để xem lại thay đổi.

Muốn cấu hình từng bước theo kiểu hỏi đáp, README có lệnh:

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

### Mở lại Claude Code

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu đang mở sẵn, hãy thoát ra rồi mở lại.

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

Nếu bạn không muốn thêm file vào dự án, dùng đường plugin. Gõ các lệnh sau bên trong Claude Code (không phải ở terminal thường):

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

Đường này cài công cụ lõi, console và các mod, không thêm file vào dự án. Nhưng README cũng cho biết nó ít tính năng hơn: không có hook, và chỉ `ruflo-core` mới đăng ký MCP server. 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
```

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

Với Codex hoặc client MCP khác, README hướng dẫn cấu hình **command** là `npx` và **arguments** là `["-y", "ruflo@latest", "mcp", "start"]`. Tức là client sẽ chạy lệnh này:

```bash
npx -y ruflo@latest mcp start
```

Mỗi client có chỗ điền cấu hình MCP khác nhau. README chưa ghi chi tiết từng client, bạn xem tài liệu của client đó để biết điền vào đâu.

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

Theo README, cách kiểm tra đơn giản nhất là:

1. Chạy `npx ruflo@latest init` xong, mở lại Claude Code trong cùng thư mục.
2. Gõ `/ruflo` để mở console. Nếu bảng điều khiển hiện ra, phần console đã hoạt động.
3. Với đường plugin, gõ `/plugin` để xem danh sách. README nói các mod đã cài sẽ xuất hiện ở dòng mod đang hoạt động.

Ngoài ra, bạn có thể chạy console ngay ở terminal thường, không cần Claude Code:

```bash
npx ruflo tui
```

Thêm `--plain` nếu bạn muốn in ra một khung hình duy nhất để dùng trong script. Thấy giao diện console hiện lên là Ruflo chạy được. Việc agent làm tốt hay không thì phải thử bằng một tác vụ thật, như các tình huống bên dưới.

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

### 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ũ, chưa biết module nào dễ hỏng. Sau khi `init` và mở lại Claude Code, bạn dán đú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.
```

Nhóm agent sẽ tìm module rủi ro nhất, viết test cho nó rồi tóm tắt thay đổi. Bạn nên đọc kỹ phần tóm tắt và xem diff trước khi giữ lại thay đổi nào.

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

### Người mới muốn thử console mà vẫn giữ quyền kiểm soát

Bạn muốn xem Claude điều khiển bảng theo dõi, nhưng không muốn nó tự làm gì ngoài ý bạn. Làm theo các bước README gợi ý. Cài console bằng các lệnh plugin ở trên, mở `/ruflo`, vào Settings → Claude control, 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 sẽ mở mục Missions và đặt mục tiêu. 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, mục 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. Muốn dừng, bấm “Take back control”.

### Người dùng Codex hoặc công cụ khác muốn dùng chung bộ công cụ

Bạn không dùng Claude Code mà dùng Codex hoặc một client hỗ trợ MCP. Bạn cấu hình client chạy lệnh `npx -y ruflo@latest mcp start` như phần cài đặt. Không cần chạy `init` cho dự án. Kết quả: client của bạn nhìn thấy các công cụ MCP của Ruflo và gọi chúng khi cần. README chưa kể chi tiết từng công cụ làm gì trong từng client, nên bạn thử từng việc nhỏ trước.

### Chạy giao diện theo dõi trên máy chủ hoặc trong script

Bạn làm việc ở terminal thuần, hoặc muốn lấy nhanh trạng thái để đưa vào script. Chạy:

```bash
npx ruflo tui
```

Hoặc thêm `--plain` để in một khung hình rồi thoát, phù hợp khi cần ghi ra file hay đưa vào công cụ khác. Kết quả là một ảnh chụp trạng thái workflow, agent và chi phí, không cần mở Claude Code.

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

**Lệnh `npx` báo lỗi hoặc không chạy.** Hầu hết do Node quá cũ hoặc chưa cài. Chạy `node --version`. Repo yêu cầu Node 20 trở lên, nên hãy cập nhật rồi chạy lại.

**Mở Claude Code nhưng không thấy gì mới.** Claude Code chỉ nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn, mở lại **trong đúng thư mục** bạn đã chạy `init`. Nếu mở ở thư mục khác, nó sẽ không thấy gì.

**Lệnh `/plugin` hoặc `/ruflo` không hoạt động.** Có thể Claude Code của bạn cũ. README yêu cầu bản 2.1.287 trở lên cho đường plugin. Hãy cập nhật Claude Code, chạy `/reload-plugins`, rồi mở `/plugin` xem plugin đã nằm trong danh sách chưa.

**Claude từ chối thực hiện một hành động trong console.** Đây là hành vi theo thiết kế: hành động vượt mức quyền bạn đặt sẽ bị từ chối. Mặc định chỉ là read + ask. Nếu cần ghi, bạn tự nâng lên write, nhưng hãy nâng từng mức và giữ chế độ `ask` để tự duyệt. Hành động tốn tiền, đụng mạng hoặc phá hủy luôn cần xác nhận.

**Cài cùng một plugin từ hai nơi nên bị chạy đôi.** README cảnh báo với các plugin bên ngoài như `agentdb`, `agentic-flow`, `agentic-qe-fleet`: nên cài từ một marketplace thôi. Cài cả hai thì mod và lệnh bị nạp hai lần. Nếu thấy lệnh xuất hiện trùng, gỡ một bản.

```note
README ghi rõ: các mod chạy với quyền của tài khoản bạn và không bị đặt trong sandbox. Hãy đọc code của mod trước khi cài, nhất là khi dùng ở máy có dữ liệu công việc quan trọng.
```

## 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. Có đủ lớp từ điều phối, bộ nhớ đến bảo mật và theo dõi chi phí. Cơ chế quyền trong console (read/write/manage/full, ask/auto) cho bạn kiểm soát rõ. Dùng được với cả Claude Code lẫn Codex và client MCP khác. Dự án vẫn được cập nhật đều.

**Giới hạn.** Hệ thống rất lớn, gồm hàng chục plugin, nên dễ bị ngợp. Hãy bắt đầu bằng `init` và một việc nhỏ. Đường `init` thêm khá nhiều file vào dự án. Đường plugin sạch hơn nhưng ít tính năng hơn. Một số phần trong README được tác giả ghi rõ là mô tả khái niệm, và các video 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. Vì vậy bạn nên tự kiểm chứng kết quả. README cũng chưa nói rõ về Windows hay yêu cầu phần cứng.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code làm vài việc đơn giản, dùng Claude Code trơn là đủ. Nếu bạn muốn thử một chức năng riêng lẻ mà không muốn đụng vào dự án, hãy cài đúng một plugin thay vì toàn bộ. Nếu dữ liệu rất nhạy cảm, hãy đọc kỹ SECURITY.md và code của mod trước khi dùng.

## 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 Ruflo chạy cùng Claude Code hoặc Codex, nên chi phí token vẫn theo tài khoản của bạn ở các công cụ đó. Tư liệu chưa có thông tin về gói trả phí riêng của Ruflo.

### Ruflo khác gì Claude Code?

Claude Code là công cụ để bạn làm việc với AI viết code. Ruflo là lớp bao quanh nó, thêm các agent chuyên biệt, nhóm agent phối hợp (swarm), bộ nhớ qua nhiều phiên, hook và console theo dõi. README gọi đó là agent harness. Ruflo không thay Claude Code mà chạy cùng nó.

### Cài Ruflo cần gì?

Cần Node.js 20 trở lên, vì package.json yêu cầu vậy, và một công cụ như Claude Code hoặc Codex. Cài bằng plugin trong Claude Code cần bản 2.1.287 trở lên. README chưa nói gì về yêu cầu RAM hay GPU.

### Dùng được với Codex hoặc công cụ khác ngoài Claude Code không?

Được. README cho biết 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"]. Chỗ điền cấu hình tùy từng client, bạn xem tài liệu của client đó.

### Ruflo có tự ý làm việc nguy hiểm không, dữ liệu có an toàn không?

Console cho bạn đặt mức quyền read, write, manage hoặc full và chọn ask hoặc auto. Mặc định hiện là read + ask, và hành động tốn tiền, đụng mạng hay phá hủy luôn cần xác nhận. Tuy vậy README cảnh báo các mod chạy với quyền tài khoản của bạn và không có sandbox, nên bạn phải đọc code trước khi cài.

### Cài Ruflo có thêm file vào dự án của tôi không?

Có nếu bạn dùng npx ruflo@latest init: README nói nó tạo thư mục .claude/, .claude-flow/, file CLAUDE.md và một số file hỗ trợ. Nếu chọn cài chỉ bằng plugin trong Claude Code thì README ghi là không thêm file nào vào dự án, nhưng bạn sẽ có ít tính năng hơn.

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

Tư liệu README mà mình có chưa nói rõ về hệ điều hành được hỗ trợ. Cái chắc chắn là cần Node 20 trở lên. Bạn nên xem README.md và thư mục docs trong repo, hoặc thử với một dự án nhỏ trước.
