# 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 "harness" bao quanh Claude Code và Codex, thêm nhiều agent chuyên biệt, bộ nhớ dài hạn, hook và MCP server. Bạn dùng nó để giao việc lớn cho một nhóm agent phối hợp với nhau thay vì một AI làm một mình. Cài khá đơn giản: một lệnh `npx ruflo@latest init` 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-14 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-ai-agent-claude-code-codex-huong-dan-10

Ruflo là một lớp điều phối (harness) đặt quanh Claude Code và Codex. Nó bổ sung những thứ mà một AI viết code đơn lẻ thường thiếu: nhiều agent chuyên biệt, bộ nhớ giữ lại giữa các phiên, hook tự chạy và một MCP server. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, giấy phép MIT.

Nếu bạn đã dùng Claude Code và thấy nó hay "quên" việc cũ, hoặc muốn giao một việc lớn như "rà soát cả repo, viết test, tóm tắt thay đổi" cho nhiều agent cùng làm, Ruflo nhắm đúng vào chỗ đó. Người mới cũng dùng được: sau khi cài, bạn cứ dùng Claude Code như bình thường, phần điều phối chạy nền.

Điểm đáng giá nhất là cách cài rất ngắn gọn: một lệnh trong thư mục dự án, mở lại Claude Code là xong. Ngoài ra còn có đường cài "nhẹ" qua plugin của Claude Code, không thêm file nào vào dự án của bạn.

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

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

Theo README, công thức là "Agent = Model + Harness". Model viết code, còn harness đưa cho nó công cụ, bộ nhớ, vòng lặp và các giới hạn kiểm soát. Ruflo đóng vai harness đó. Cụ thể:

- **Nhiều agent chuyên biệt chạy thành nhóm (swarm).** 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 việc lớn, hệ thống chia cho nhiều agent thay vì để một agent ôm hết.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ được kinh nghiệm từ các việc trước và dùng lại. 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 và học.** Sau khi `init`, hook sẽ tự chuyển việc cho đúng agent và ghi lại mẫu làm việc thành công. Bạn không phải học hết 406 công cụ MCP hay 61 lệnh CLI mà README nhắc tới.
- **Console "buồng lái" ngay cạnh Claude Code.** Gõ `/ruflo` để xem workflow, agent, model, token và chi phí. Bạn có thể mở log từng lần chạy, tìm kiếm, xem lỗi, chạy lại và so sánh.
- **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 `read`, `write`, `manage`, `full` và hai chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. 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, kể cả khi để `auto`.
- **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.
- **Liên kết (federation).** Agent trên các máy khác nhau có thể trao đổi với nhau. Phần này dành cho người dùng nâng cao, người mới chưa cần đụng tới.
- **Dùng được với Codex và client MCP khác.** Chỉ cần trỏ client tới lệnh `npx -y ruflo@latest mcp start`.

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

Tư liệu chỉ nêu rõ vài thứ:

- **Node.js từ 20.0.0 trở lên** (theo `package.json`). Bạn cần có `npx` đi kèm Node.
- **Claude Code** đã cài, nếu bạn đi đường `init` hoặc đường plugin. Riêng đường plugin cần Claude Code **2.1.287 trở lên**; lệnh cài từ terminal (`claude plugin install ...`) cần **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy lệnh. Với đường `init`, Ruflo sẽ thêm file vào chính thư mục này.
- Nếu dùng Codex hoặc client MCP khác: client đó phải cho phép khai báo một MCP server bằng lệnh và tham số.

README không nói về yêu cầu GPU, hệ điều hành cụ thể hay API key riêng cho Ruflo. Các thông tin đó chưa có trong tư liệu mình có. Bạn vẫn cần tài khoản/quyền truy cập Claude Code hoặc Codex như bình thường để agent làm việc.

Một chi tiết dễ gây rối: tên gói npm trong repo là `claude-flow` (có lệnh CLI), nhưng README hướng dẫn gọi `ruflo` qua `npx`. Bạn cứ làm đúng theo README là được.

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

Có ba đường: (A) `init` vào dự án, (B) chỉ cài plugin trong Claude Code, (C) nối Codex hoặc client MCP khác. Phần dưới đi theo đường A trước vì README gọi đây là cách chính. README nói đường này hợp cho dùng thật vì mọi thứ chạy đúng như tài liệu.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án mà bạn muốn Ruflo hỗ trợ
- Chạy init | Gõ npx ruflo@latest init để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude Code | Mở Claude Code ở cùng thư mục để nó nạp cấu hình mới
- Giao việc thử | Đưa một việc thật và để Ruflo điều phối
- (Tuỳ chọn) Cài bằng plugin | Cách nhẹ, không thêm file vào dự án
```

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

Lệnh `init` ghi file vào thư mục hiện tại, nên chỗ này quan trọng nhất. Trên Windows, bạn có thể mở PowerShell rồi dùng `cd` để vào thư mục dự án. Chưa có dự án thì tạo một thư mục thử để làm quen trước.

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

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

### Chạy lệnh init

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

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

`npx` tải và chạy bản mới nhất của Ruflo mà không cần cài toàn cục. README nói `init` thêm agent, hook, bộ nhớ và MCP server vào dự án. Bảng so sánh trong README cho biết bản này tạo các mục 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 sau khi chạy.

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

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

```note
Init sẽ thêm file vào dự án. Hãy thử trên một thư mục có Git hoặc đã sao lưu, để bạn dễ xem Ruflo đã thay đổi gì và hoàn tác nếu cần.
```

### Mở lại Claude Code và giao việc thử

Mở Claude Code ở cùng thư mục. README nói Claude Code sẽ nạp cấu hình mới ở lần khởi động kế tiếp, nên nếu Claude Code đang mở sẵn thì bạn hãy đóng và mở lại. Sau đó thử một việc thật, ví dụ 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.
```

Câu này bảo Claude dùng swarm của Ruflo để rà soát 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 câu gốc.

### 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. README ghi nó cài công cụ lõi, console trực quan và các mod chạy trong tiến trình. 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
```

Dòng đầu thêm "chợ" plugin của Ruflo. Ba dòng `install` cài từng plugin. `/reload-plugins` nạp lại, còn `/ruflo` mở console. Nếu bạn dùng Claude Code 2.1.292 trở lên và muốn cài từ terminal thường, README cho lệnh:

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

```note
Các mod chạy với quyền tài khoản của bạn và không được cô lập (sandbox). README dặn hãy đọc code trước khi cài. Plugin cũng chỉ cho bạn một phần tính năng, không đầy đủ như bản `init`.
```

### Cách khác: Codex hoặc client MCP khác

Không cần cài sẵn gì thêm. Trong cài đặt MCP của client, khai báo **command** là `npx` và **arguments** là:

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

Cách khai báo cụ thể (file nào, giao diện nào) tuỳ từng client. README chưa hướng dẫn chi tiết cho từng client, nên bạn xem tài liệu của client đó và thư mục `docs/` trong repo.

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

Theo README, bạn có thể kiểm tra như sau:

1. Sau `init`, mở lại Claude Code trong thư mục dự án rồi gõ `/ruflo`. Console "buồng lái" xuất hiện là dấu hiệu tốt.
2. Với đường plugin, mở `/plugin` và kiểm tra các mod (ví dụ `ruflo-console`, `ruflo-mods`) có hiện trong dòng "active mods".
3. Trong thư mục dự án, nếu dùng `init`, bạn sẽ thấy các mục như `.claude/`, `.claude-flow/` và `CLAUDE.md` được tạo hoặc cập nhật.
4. Muốn thử giao diện terminal riêng, không cần Claude Code, chạy:

```bash
npx ruflo tui
```

Thêm `--plain` nếu bạn chỉ muốn in ra một khung hình, tiện cho script. README chưa mô tả chi tiết kết quả mong đợi ngoài việc console hiện lên, nên mình không nêu thêm.

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

### Dev rà soát một dự án có sẵn

**Bối cảnh:** bạn nhận một repo từ đồng nghiệp, không biết chỗ nào dễ hỏng, test thì thưa thớt.

**Làm thế nào:** chạy `npx ruflo@latest init` trong repo, mở lại Claude Code rồi giao 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ả:** Claude điều phối nhóm agent để xác định module rủi ro nhất, viết test và tóm tắt thay đổi. Bạn đọc phần tóm tắt, xem lại test và chạy thử trước khi giữ lại.

> Bạn không cần học 406 công cụ. Cài xong cứ dùng Claude Code như bình thường, phần điều phối để Ruflo lo.
>
> — Ông T

### Người dùng muốn "cầm lái" bằng console

**Bối cảnh:** bạn muốn nhìn thấy agent đang làm gì, tốn bao nhiêu token, chứ không muốn tin mù quáng.

**Làm thế nào:** cài console theo đường plugin (như phần trên), gõ `/ruflo`, vào **Settings → Claude control** và chọn **write + ask**. Rồi nhờ Claude, theo ví dụ của README: "Create a mission to add a dark mode toggle. Show me the mission and its status."

**Kết quả:** Claude mở mục Missions và đặt mục tiêu, bạn xác nhận thao tác tạo. Sau đó 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. Nếu muốn dừng, bấm **Take back control**.

### Người dùng Codex hoặc client MCP khác

**Bối cảnh:** bạn không dùng Claude Code mà dùng Codex, hoặc một công cụ khác hỗ trợ MCP, và muốn có bộ nhớ cùng công cụ của Ruflo.

**Làm thế nào:** khai báo 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 có thêm các công cụ MCP của Ruflo mà không cần chạy `init` trong dự án. Mức độ hỗ trợ cụ thể phụ thuộc client, README không cam kết chi tiết.

### Muốn thử mà không đụng vào dự án

**Bối cảnh:** bạn quản lý một thư mục quan trọng và chưa muốn có thêm file lạ.

**Làm thế nào:** đi đường plugin. Bắt đầu với `/plugin marketplace add ruvnet/ruflo`, rồi cài `ruflo-core`. Cần thêm tính năng thì cài tiếp từng plugin, ví dụ `ruflo-swarm` để điều phối nhiều agent, `ruflo-rag-memory` cho truy xuất thông minh hơn, hay `ruflo-cost-tracker` để theo dõi token và ngân sách.

**Kết quả:** bạn có lệnh slash và định nghĩa agent mà không có file nào được thêm vào workspace. Đổi lại, README nói rõ đường này không có hook và không có đầy đủ như bản `init`.

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

### Node quá cũ, `npx` báo lỗi

`package.json` yêu cầu Node từ 20.0.0. Nếu máy bạn đang dùng bản cũ hơn, lệnh có thể lỗi ngay. Kiểm tra bằng `node --version`, cập nhật Node lên bản 20 trở lên rồi chạy lại `npx ruflo@latest init`.

### Cài plugin báo không nhận lệnh

Đường plugin cần Claude Code 2.1.287 trở lên (lệnh cài từ terminal cần 2.1.292 trở lên). Nếu Claude Code của bạn cũ hơn, hãy cập nhật trước. Cài xong mà chưa thấy lệnh mới thì thử `/reload-plugins`, hoặc đóng và mở lại Claude Code.

### Mở Claude Code nhưng không thấy gì mới sau `init`

README nói Claude Code nạp cấu hình ở lần khởi động kế tiếp. Hãy chắc là bạn mở Claude Code **đúng thư mục** đã chạy `init`. Nếu sai thư mục, nó sẽ không thấy `.claude/` và các file liên quan.

### Plugin bị nạp hai lần

Với một số plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`, README dặn chỉ cài từ **một** marketplace, hoặc marketplace gốc của plugin đó hoặc của `ruflo`. Cài từ cả hai thì mod và lệnh bị nạp đôi. Nếu thấy lệnh bị trùng, gỡ một bản đi.

### Claude bị từ chối khi điều khiển console

Đây là thiết kế chứ không phải lỗi. Thao tác vượt quá mức quyền bạn chọn trong Claude control sẽ bị từ chối, và các việc liên quan mạng, chi tiêu, phá huỷ luôn cần xác nhận. Nếu muốn Claude được phép nhiều hơn, bạn nâng mức quyền một cách chủ động và cân nhắc. Đừng bật `auto` với mức `full` nếu chưa hiểu rõ.

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

**Điểm mạnh:**

- Cài nhanh: một lệnh `npx` và mở lại Claude Code.
- Có đường nhẹ (plugin) để thử mà không động vào dự án.
- Console cho phép nhìn, kiểm tra và chạy lại từng lần làm việc của agent, thay vì tin mù quáng.
- Quyền hạn của Claude trong console được bạn đặt rõ, mặc định là mức thấp.
- 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:**

- Hệ thống rất lớn: 48 plugin, hàng trăm công cụ. Người mới dễ choáng, nên bắt đầu với `init` rồi dùng như bình thường, đừng cố học hết.
- README tự nói phần "học liên tục" mới ở mức khái niệm, và một số demo dùng dữ liệu mẫu, không chứng minh được việc swarm đã làm xong thật. Hãy tự kiểm tra kết quả.
- Bản `init` thêm khá nhiều file vào dự án. Bản plugin thì nhẹ nhưng ít tính năng.
- Mod chạy với quyền tài khoản của bạn và không có sandbox, nên cần đọc code trước khi cài.
- Chi phí token khi chạy nhiều agent cùng lúc: README chưa đưa số liệu cụ thể, nên hãy theo dõi bằng console hoặc plugin `ruflo-cost-tracker`.

**Nên chọn cách khác khi:** bạn chỉ cần một AI trả lời nhanh vài câu hỏi, hoặc dự án nhỏ đến mức việc điều phối nhiều agent là thừa. Lúc đó dùng Claude Code hoặc Codex thuần sẽ đơn giản và rẻ hơn.

## 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ã tự do. Tuy nhiên agent vẫn gọi Claude Code, Codex hoặc nhà cung cấp AI khác, nên chi phí của các dịch vụ đó thì bạn vẫn chịu. README chưa nêu bảng giá cụ thể.

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

File package.json yêu cầu Node từ 20.0.0 trở lên. Bạn dùng lệnh npx đi kèm Node để chạy `npx ruflo@latest init`. Nếu dùng đường plugin thì cần thêm Claude Code từ 2.1.287 trở lên.

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

Tư liệu mình có không nói Ruflo bắt buộc GPU. README chỉ nhắc một plugin riêng (`ruflo-ruvector`) có tìm kiếm tăng tốc bằng GPU, đây là tính năng tuỳ chọn. Với phần còn lại, chưa có thông tin về yêu cầu phần cứng.

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

README không nêu rõ danh sách hệ điều hành được hỗ trợ. Lệnh cài chỉ là `npx ruflo@latest init` nên về nguyên tắc cần Node và terminal. Bạn nên thử trên một thư mục thử trước khi dùng cho dự án quan trọng.

### Khác gì so với dùng Claude Code thuần?

Ruflo là lớp bao quanh Claude Code (và Codex), thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên, hook tự định tuyến và một console theo dõi. Nó không thay thế Claude Code mà chạy cùng nó. Bạn vẫn dùng Claude Code như bình thường.

### Dữ liệu và quyền truy cập có an toàn không?

README cho biết console để mức Claude control mặc định là read + ask, và các thao tác liên quan mạng, chi tiêu hoặc phá huỷ luôn cần xác nhận. Tuy nhiên 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 cần đọc code trước khi cài. Repo cũng có tệp SECURITY.md để bạn xem thêm.

### Có 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, bằng cách khai báo command `npx` với tham số `-y`, `ruflo@latest`, `mcp`, `start`. Cách cấu hình cụ thể tuỳ từng client và README chưa hướng dẫn chi tiết từng công cụ.
