# Ruflo: điều phối nhóm agent cho Claude Code và Codex — hướng dẫn cài đặt và dùng

> Ruflo (trước đây là Claude Flow) là lớp điều phối đặt quanh Claude Code và Codex. Nó thêm các agent chuyên biệt, bộ nhớ qua nhiều phiên, hook và MCP server vào dự án của bạn. Cài chỉ cần một lệnh `npx ruflo@latest init` trong thư mục dự án, yêu cầu Node 20 trở lên.

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

Ruflo là một “harness” (bộ khung điều phối) đặt quanh Claude Code và Codex. Nói đơn giản: mô hình AI lo viết code, còn Ruflo lo phần còn lại, gồm công cụ, bộ nhớ, vòng lặp làm việc và các giới hạn an toàn. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) tạo ra.

Nếu bạn đã dùng Claude Code và thấy một agent đơn lẻ hay quên ngữ cảnh, hay làm một việc lớn quá chậm, Ruflo là hướng để thử. Nó cho phép nhiều agent chia việc theo kiểu “bầy” (swarm), nhớ kinh nghiệm giữa các phiên làm việc, và có giao diện theo dõi ngay cạnh Claude Code. Người nên dùng là lập trình viên, hoặc người làm kinh doanh đã quen mở terminal và muốn thử cách làm việc với AI bài bản hơn.

Điểm đáng giá nhất là cách cài rất ngắn. Một lệnh trong thư mục dự án là đủ, sau đó bạn cứ dùng Claude Code như bình thường. README nói rõ bạn không cần học hết hàng trăm công cụ MCP hay hàng chục lệnh CLI. Hiện repo có khoảng 81.582 sao và 9.607 fork, giấy phép MIT.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, hook và MCP server, cài bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Theo tư liệu, Ruflo thêm một “hệ thần kinh” cho Claude Code. Dưới đây là những phần bạn sẽ chạm tới nhiều nhất.

- **Nhiều agent chuyên biệt làm việc theo nhóm.** Nhánh cài bằng CLI đi kèm 98 agent, hơn 60 lệnh và 30 skill. Lợi ích: bạn giao một việc lớn (ví dụ rà soát cả repo), các agent tự chia nhau thay vì một agent ôm hết.
- **Bộ nhớ qua nhiều phiên.** Agent lưu và gọi lại kinh nghiệm của các lần làm trước. Lợi ích: lần sau bạn đỡ phải giải thích lại bối cảnh dự án.
- **Hook tự định tuyến việc.** Sau khi `init`, hook 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ụ.
- **MCP server.** Ruflo chạy như một MCP server nên Codex hoặc các client MCP khác cũng dùng được, không chỉ Claude Code.
- **Bảng điều khiển (console) ngay trong Claude Code.** Xem workflow, agent, mô hình, token và chi phí. Bạn có thể mở log, tìm kiếm, xem lại và so sánh các lần chạy.
- **Cho Claude lái, bạn đặt giới hạn.** Trong Settings → Claude control, bạn chọn mức `read`, `write`, `manage` hoặc `full`, cùng 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 hay phá huỷ vẫn phải xác nhận kể cả ở chế độ `auto`.
- **Kho plugin.** README liệt kê 48 plugin cộng 3 plugin bên ngoài, 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 test còn thiếu và sinh test, `ruflo-cost-tracker` theo dõi token và cảnh báo ngân sách, `ruflo-aidefence` chặn prompt injection.
- **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 một cách an toàn. Đây là phần nâng cao, người mới chưa cần.

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

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

- **Node.js từ phiên bản 20.0.0 trở lên** (theo `package.json`). Lệnh `npx` đi kèm Node nên bạn không cần cài thêm gì.
- **Claude Code** nếu bạn đi theo đường chính. Muốn dùng đường “chỉ plugin” thì cần Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install ...` từ terminal cần **2.1.292 trở lên**.
- **Codex hoặc client MCP khác** là lựa chọn thay thế nếu bạn không dùng Claude Code.
- Một dự án (thư mục) để chạy `init` trong đó.

Về hệ điều hành, GPU hay API key riêng cho Ruflo: README phần mình có không nói rõ, nên mình không khẳng định. Bạn xem thêm trong thư mục `docs/` và `README.md` của repo.

```note
Mod và plugin chạy với quyền của tài khoản bạn và không có sandbox. README khuyên đọc code trước khi cài. Ngoài ra, khi cho Claude điều khiển console, hãy giữ mức thấp (read hoặc write kèm ask) cho tới khi bạn quen.
```

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

Có ba đường: cài đầy đủ bằng CLI (khuyên dùng), chỉ cài plugin vào Claude Code, hoặc nối qua MCP cho Codex. Mình đi theo đường chính trước.

```steps
- Mở terminal | Vào đúng thư mục dự án của bạn
- Chạy init | Dùng npx để thêm agent, hook, bộ nhớ, MCP server vào dự án
- 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
- Mở console | Gõ /ruflo để xem bảng điều khiển
- Thử một việc thật | Giao cho Claude một tác vụ có dùng swarm
```

### Mở terminal đúng thư mục

Chỗ người mới hay vấp nhất: lệnh `init` ghi file vào **thư mục hiện tại**. Vì vậy hãy mở terminal ngay trong thư mục dự án của bạn trước khi chạy. Nếu bạn dùng VS Code, mở thư mục dự án rồi mở terminal tích hợp là chắc nhất.

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

Thay `duong-dan-toi-du-an-cua-ban` bằng đườ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
```

Lệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh trong README, nhánh này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng một số file hỗ trợ và cài đặt. Nên dùng cho dự án có quản lý bằng git để bạn xem được chính xác những gì đã thay đổi.

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

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

### Khởi động lại Claude Code

Mở Claude Code trong cù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 đang mở sẵn, hãy thoát và mở lại.

### Cách khác: chỉ cài plugin, không thêm file vào dự án

Đường này không thêm file nào vào thư mục dự án. Nó cài công cụ lõi, console và mod. 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
```

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

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

Lưu ý: README cho biết đường plugin chỉ cho một phần chức năng (lệnh slash, skill, định nghĩa agent), không có hook. Muốn dùng đủ vòng làm việc, hãy chọn `npx ruflo@latest init`.

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

Không cần cài vào dự án. Trong phần cấu hình MCP của client, đặt **command** là `npx` và **arguments** là `["-y", "ruflo@latest", "mcp", "start"]`. Cú pháp cụ thể phụ thuộc vào từng client, bạn xem tài liệu của client đó để biết điền vào đâu. Dạng một dòng tương đương là:

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

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

Bảng điều khiển cũng chạy độc lập, không cần Claude Code:

```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

Theo README, các dấu hiệu cài thành công là:

1. Sau `npx ruflo@latest init`, thư mục dự án có thêm các thư mục như `.claude/` và `.claude-flow/` cùng file `CLAUDE.md`.
2. Mở lại Claude Code trong thư mục đó rồi gõ `/ruflo`. Bảng điều khiển (console) hiện ra là cài đúng.
3. Với đường plugin, gõ `/plugin` và kiểm tra các plugin có xuất hiện trong dòng mod đang hoạt động.
4. Với Codex, client MCP kết nối được và liệt kê công cụ của Ruflo.

Nếu `npx` báo lỗi phiên bản, kiểm tra Node bằng `node --version`. Bạn cần từ 20 trở lên.

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

README nhấn mạnh: sau `init`, cứ dùng Claude Code như bình thường, phần điều phối chạy ngầm. Dưới đây là các tình huống bám theo ví dụ trong tư liệu.

### Rà soát một repo cũ trước khi nhận bàn giao

Bạn là lập trình viên mới nhận một dự án chưa ai viết test. Sau khi cài xong, mở Claude Code trong thư mục dự án và gõ câu mẫu của chính README:

```text
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.
```

Claude sẽ dùng swarm để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn xem lại diff trước khi giữ thay đổi.

> Agent = Model + Harness. 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.
>
> — Ông T

### Theo dõi chi phí và tiến độ khi giao việc dài

Bạn là chủ một nhóm nhỏ, dùng Claude Code cho nhiều việc cùng lúc và muốn biết token cũng như chi phí đang đi đâu. Mở console bằng `/ruflo`. Theo README, console cho xem workflow, agent, mô hình, token và chi phí, đồng thời cho mở log và kết quả từng agent để tìm chỗ lỗi. Nếu muốn thêm cảnh báo ngân sách, plugin `ruflo-cost-tracker` có chức năng theo dõi token, đặt ngân sách và báo khi vượt.

### Tạo một “mission” có kiểm soát

Đây là quy trình README mô tả để làm quen với chế độ cho Claude điều khiển console:

1. Vào `/ruflo`, chọn **Settings → Claude control → write + ask**.
2. Gõ yêu cầu cụ thể, ví dụ: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
3. Claude mở mục Missions và đặt mục tiêu. Bạn xác nhận hành động tạo đang chờ.
4. Kiểm tra mục Missions có mục tiêu và Overview có ghi lại hành động.

Kết quả: bạn có một mission được ghi nhận. README lưu ý 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**.

### Nối Ruflo vào Codex hoặc công cụ MCP khác

Bạn không dùng Claude Code mà dùng Codex. Thêm một MCP server với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Từ đó client của bạn gọi được các công cụ điều phối và bộ nhớ của Ruflo mà không cần thêm file nào vào dự án.

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

**`npx` chạy báo lỗi hoặc không tìm thấy lệnh.** Thường do chưa cài Node hoặc Node quá cũ. Kiểm tra bằng `node --version`, cần từ 20 trở lên rồi chạy lại.

**Chạy `init` nhưng Claude Code không thấy gì mới.** Claude Code chỉ nhận cấu hình khi khởi động. Hãy thoát hẳn rồi mở lại, và chắc chắn bạn mở đúng thư mục đã chạy `init`.

**Lệnh `/plugin install` không nhận hoặc không có `/ruflo`.** Có thể Claude Code của bạn quá cũ. Đường plugin cần 2.1.287 trở lên, còn lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên. Sau khi cài, gõ `/reload-plugins`.

**Cài plugin xong nhưng thấy ít chức năng hơn mô tả.** Đây là đúng thiết kế: đường plugin chỉ là bản nhẹ, không có hook và không đăng ký đủ MCP. Muốn đủ vòng làm việc, dùng `npx ruflo@latest init`.

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

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

**Điểm mạnh.** Cài nhanh, một lệnh. Dùng được với cả Claude Code lẫn Codex. Có console để nhìn thấy agent đang làm gì, và có cơ chế phân quyền rõ (read/write/manage/full, ask/auto). Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Hệ sinh thái khá lớn: hàng chục plugin, hàng trăm công cụ MCP, nên người mới dễ choáng. Hãy bắt đầu với `init` và một tác vụ nhỏ. `init` thêm nhiều file vào dự án, nên nên chạy trên nhánh git riêng. Mod không có sandbox. README cũng nói thẳng rằng các bản demo hoạt ảnh dùng dữ liệu mẫu, không phải bằng chứng đã hoàn thành việc thật. Phần học tự động cũng vẫn cần cấu hình embedding.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code trả lời vài câu hỏi hay sửa một file, bộ khung này là thừa. Nếu bạn muốn không thêm file nào vào dự án, đi đường plugin hoặc MCP. Nếu bạn cần biết chính xác Ruflo chạy trên hệ điều hành nào hay tốn bao nhiêu chi phí, hãy đọc kỹ `docs/` trong repo trước, vì phần tư liệu mình có chưa nói rõ.

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

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

Mã nguồn Ruflo theo giấy phép MIT, nên dùng và sửa được tự do. Tuy vậy, Ruflo chạy cùng Claude Code hoặc Codex, và chi phí của các dịch vụ AI đó tính riêng. Tư liệu chưa nói chi tiết về giá của từng nhà cung cấp.

### Ruflo khác gì dùng Claude Code trực tiếp?

Ruflo không thay Claude Code mà đặt thêm một lớp điều phối bên ngoài. Lớp này thêm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook và bảng điều khiển. Mô hình vẫn là Claude hoặc Codex, Ruflo chỉ bổ sung công cụ và kiểm soát.

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

Đường chính chỉ một lệnh là npx ruflo@latest init chạy trong thư mục dự án, sau đó mở lại Claude Code. Bạn cần Node từ phiên bản 20 trở lên. Ngoài ra còn đường chỉ cài plugin và đường MCP cho Codex.

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

Tư liệu mình có chưa nêu yêu cầu GPU hay hệ điều hành cụ thể. Điều chắc chắn là cần Node 20 trở lên. Bạn nên xem thêm thư mục docs trong repo 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 dùng npx ruflo@latest init. README cho biết nó thêm các thư mục như .claude/ và .claude-flow/ cùng file CLAUDE.md. Nếu không muốn thêm file nào, dùng đường plugin Claude Code hoặc nối qua MCP.

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

Bạn tự đặt giới hạn: read, write, manage hoặc full, kèm chế độ 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 và phá huỷ vẫn cần xác nhận kể cả khi ở auto, và bạn có thể bấm Take back control để dừng.

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

Được. README nói Codex và các client MCP khác chạy được bằng cách trỏ tới lệnh npx với tham số -y, ruflo@latest, mcp, start. Cách điền cấu hình cụ thể tuỳ từng client.
