# Ruflo: điều phối nhiều 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 mã nguồn mở: lớp công cụ bọc quanh Claude Code và Codex để thêm đội agent, bộ nhớ dài hạn, hook và MCP server. Bạn dùng nó để giao việc lớn cho nhiều agent phối hợp thay vì một cuộc trò chuyện đơn lẻ. 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-21 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-ai-claude-code-codex-huong-dan

Ruflo là một “agent meta-harness” mã nguồn mở cho Claude Code và Codex. Nói đơn giản: mô hình AI lo việc viết, còn Ruflo là bộ đồ nghề bao quanh nó. Bộ đồ nghề này 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 để AI làm được việc thật. Repo trước đây có tên Claude Flow, hiện có khoảng 81.582 sao và 9.607 fork trên GitHub.

Vấn đề repo giải quyết khá quen thuộc. Khi bạn dùng Claude Code cho việc lớn, mỗi phiên làm việc thường bắt đầu lại từ đầu, và chỉ có một “người” làm mọi thứ. Ruflo thêm vào đó nhiều agent chuyên biệt, cách để chúng chia việc cho nhau (gọi là swarm), và bộ nhớ để lần sau không phải giải thích lại.

Bạn nên đọc bài này nếu là lập trình viên (kể cả mới học) đang dùng Claude Code hoặc Codex. Người làm văn phòng, kinh doanh có thể theo dõi được phần cài đặt, nhưng công cụ này nghiêng về làm việc với mã nguồn. Điểm đáng giá nhất: README nói bạn không cần học hết hàng trăm công cụ bên trong. Chạy `init` xong, 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 bọc quanh Claude Code và Codex, thêm đội agent, bộ nhớ qua các phiên, hook và MCP server chỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Theo README, Ruflo bổ sung cho Claude Code và Codex những thứ sau.

- **Đội agent chuyên biệt.** README nói có hơn 100 agent chuyên biệt. Bạn không phải tự viết từng “vai” như người review, người viết test. Có sẵn rồi thì chỉ việc giao việc.
- **Swarm: nhiều agent phối hợp.** Các agent tự tổ chức thành nhóm để chia việc. Một yêu cầu như “review cả repo” có thể được chia cho nhiều agent xử lý.
- **Bộ nhớ tự học, nhớ qua các phiên.** Ruflo lưu kinh nghiệm từ các việc đã làm và đưa lại vào việc định tuyến lần sau. README lưu ý đây là luồng khái niệm, và phần học cục bộ vẫn cần cấu hình embedding.
- **Hook tự định tuyến.** Sau `init`, hệ thống hook tự phân loại việc, học từ các mẫu thành công và phối hợp agent ở phía sau.
- **MCP server.** Claude Code, Codex hay client MCP khác đều gọi được công cụ của Ruflo qua giao thức này.
- **Console trực quan (`/ruflo`).** Giống một buồng lái cạnh Claude Code: xem workflow, agent, model, token và chi phí; xem lại log, tìm kiếm, phân loại lỗi.
- **Kiểm soát quyền Claude.** Trong console, bạn chọn mức quyền cho Claude là `read`, `write`, `manage` hoặc `full`, kèm chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask, tức là an toàn nhất.
- **Federation.** Agent trên các máy khác nhau có thể nói chuyện với nhau mà README cho biết không làm lộ dữ liệu.
- **Hệ plugin lớn.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài): kiểm thử, theo dõi chi phí token, quét bảo mật, tạo tài liệu, bộ nhớ vector và nhiều thứ khác.
- **Tích hợp rộng.** Ngoài Claude Code và Codex, README còn nhắc tới Grok Build (`npx ruflo init --grok`).

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

Tư liệu repo nói rõ một số điều. Còn lại README phần đã cung cấp chưa ghi.

- **Node.js 20 trở lên.** `package.json` yêu cầu `>=20.0.0`. Cần có sẵn `npx` (đi kèm Node).
- **Claude Code** nếu bạn dùng theo hướng chính. Với cách cài bằng plugin, cần Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` ở 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.
- **Hệ điều hành, RAM, GPU:** README đoạn mình có chưa nói yêu cầu cụ thể. Mình không đoán, bạn xem thêm thư mục `docs/` trong repo.
- **API key:** phần README mình có không nêu key nào bắt buộc để chạy `init`. Claude Code hay Codex của bạn vẫn dùng tài khoản của chính bạn như bình thường.

```note
Các mod của Ruflo chạy với quyền tài khoản của bạn và không bị đưa vào sandbox. Hãy đọc mã nguồn trước khi cài. Với console, giữ mức quyền thấp (read + ask) cho đến khi bạn hiểu rõ nó làm gì.
```

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

Có nhiều đường cài. Cách đơn giản và đầy đủ nhất là chạy `npx ruflo@latest init` trong thư mục dự án.

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

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

Lệnh `init` ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong dự án của mình. Chỗ người mới hay vấp là mở terminal ở thư mục khác (ví dụ thư mục người dùng) rồi chạy lệnh. Khi đó file sẽ nằm sai chỗ.

Nếu bạn chưa có dự án, hãy tạo một thư mục thử nghiệm riêng. Nếu muốn lấy mã nguồn Ruflo về để đọc, dùng lệnh phổ thông sau:

```bash
git clone https://github.com/ruvnet/ruflo.git
cd ruflo
```

Lưu ý: bạn không cần clone repo này để dùng Ruflo theo cách chính. Chỉ clone khi muốn đọc code.

### Chạy lệnh init

Trong thư mục dự án, chạy:

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

`npx` tải và chạy Ruflo bản mới nhất, không cần cài toàn cục. README cho biết `init` thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh trong README, cách này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng một số file trợ giúp và cấu hình.

Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh:

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

Nếu dự án của bạn nằm trong git, hãy commit trước khi chạy để dễ so sánh những file mới xuất hiện.

### Mở Claude Code và giao việc

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

Sau đó thử một yêu cầu thật, ví dụ 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.
```

Bạn có thể viết yêu cầu bằng tiếng Việt cho thoải mái. Ví dụ trên bằng tiếng Anh là mẫu gốc từ README.

### Cách khác: cài qua plugin của Claude Code

Đường này không thêm file nào vào dự án của bạn. Theo README, nó cài công cụ lõi, console trực quan và các mod chạy trong tiến trình. Bạn cần Claude Code 2.1.287 trở lên. Gõ lần lượt 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 bắt đầu bằng dấu `/` và gõ ngay trong khung chat của Claude Code, không gõ ở terminal thường. 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ần biết khác biệt: README so sánh rằng cách plugin chỉ cho lệnh slash, vài skill và định nghĩa agent, không có hook. Cách `init` mới là vòng lặp đầy đủ (98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon).

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

Với Codex hoặc client MCP khác, bạn cấu hình **command** là `npx` và **arguments** như sau. Lệnh tương đương khi chạy tay là `npx -y ruflo@latest mcp start`:

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

Cách này không cần thiết lập dự án. Muốn thiết lập dự án tương tác thì dùng `npx ruflo@latest init wizard` như trên. Chỗ cấu hình cụ thể nằm ở file settings của từng client, README chưa chỉ chi tiết.

### Chạy giao diện terminal riêng

Console 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 duy nhất, tiện cho script.

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

README không đưa một lệnh “kiểm tra phiên bản” riêng. Bạn có thể tự xác nhận bằng các dấu hiệu sau.

- **Sau `init`:** thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md` (theo bảng so sánh trong README).
- **Trong Claude Code:** gõ `/ruflo` để mở console. README hướng dẫn quy trình khởi động là `npx ruflo init`, khởi động lại Claude Code, rồi `/ruflo`.
- **Với cách plugin:** gõ `/plugin` và xem dòng “active mods” có hiện các mod bạn vừa cài hay không.
- **Với console độc lập:** chạy `npx ruflo tui` và thấy giao diện hiện lên.

Bài thử an toàn nhất để biết mọi thứ thông suốt: vào console, mở Settings → Claude control, chọn write + ask, rồi nhờ Claude tạo một “mission”. Chi tiết ở phần dưới.

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

### Dev nhờ swarm review và viết test cho repo

Bối cảnh: bạn là lập trình viên mới nhận một dự án cũ, không biết chỗ nào dễ hỏng. Sau khi chạy `npx ruflo@latest init` và mở lại Claude Code, bạn gõ đúng câu README gợi ý:

```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 theo README: các agent tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Hãy đọc kỹ phần tóm tắt và chạy test bằng tay. Kết quả do AI tạo ra vẫn cần bạn kiểm tra.

> Bạn vẫn là người viết code. Ruflo chỉ lo phần điều phối.
>
> — Ông T

### Tạo “mission” trong console, có kiểm soát

Bối cảnh: bạn muốn xem Claude điều khiển console nhưng không muốn nó tự ý làm gì quá tay. Làm theo kịch bản README mô tả:

1. Cài console bằng các lệnh `/plugin` ở trên, mở `/ruflo`, chọn **Settings → Claude control → write + ask**.
2. Gõ yêu cầu: “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 duyệt thao tác tạo đang chờ.
4. Kiểm tra Missions đã có mục tiêu và Overview đã ghi lại thao tác.

Kết quả: bạn có một mission mới. README nhấn mạnh việc tạo mission không có nghĩa tính năng đã được code xong. Nút **Take back control** cho phép dừng quyền điều khiển của Claude bất cứ lúc nào.

### Thử từng plugin nhỏ mà không đụng vào dự án

Bối cảnh: bạn muốn thử riêng khả năng sinh test mà chưa muốn thêm file vào repo công ty. Dùng Path A trong README: thêm marketplace rồi cài đúng plugin cần. README liệt kê `ruflo-testgen` với mô tả “tìm test còn thiếu và tạo tự động”. Theo cùng cú pháp trong README:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
```

Kết quả: bạn có thêm lệnh slash và định nghĩa agent, và dự án vẫn không có file mới. Nhớ rằng cách này chưa có hook và chưa phải vòng lặp đầy đủ.

### Theo dõi chi phí token khi chạy agent nhiều

Bối cảnh: chủ một nhóm nhỏ lo hoá đơn khi nhiều agent chạy song song. README liệt kê plugin `ruflo-cost-tracker` (theo dõi lượng token, đặt ngân sách, cảnh báo chi phí) và console có hiển thị token cùng chi phí. Bạn cài plugin đó bằng cùng cú pháp `/plugin install … @ruflo`, và mở `/ruflo` để xem. Cách cấu hình ngân sách cụ thể README đoạn mình có chưa ghi, bạn xem trong trang hướng dẫn của plugin.

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

### Claude Code không thấy agent hoặc công cụ sau khi init

Nguyên nhân thường gặp nhất là Claude Code đang mở từ trước. README nói nó chỉ nạp cấu hình ở lần khởi động kế tiếp. Hãy thoát hẳn, mở lại trong đúng thư mục đã chạy `init`.

### Lệnh `/plugin` hoặc `claude plugin install` báo không hợp lệ

Có thể Claude Code của bạn quá cũ. Cách plugin cần bản 2.1.287 trở lên, và lệnh terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi thử lại.

### `npx` báo lỗi phiên bản hoặc không chạy

`package.json` yêu cầu Node 20 trở lên. Kiểm tra bằng `node --version`. Nếu thấp hơn, cài Node mới rồi chạy lại lệnh.

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

Với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`, README khuyên chỉ cài từ một marketplace (hoặc chính marketplace của họ, hoặc `ruflo`). Cài từ cả hai thì mod và lệnh bị nạp trùng.

### Claude bị từ chối một thao tác trong console

Đây thường không phải lỗi. README cho biết thao tác vượt mức quyền bạn đặt sẽ bị từ chối, và các thao tác liên quan mạng, chi tiêu hay phá huỷ luôn cần bạn xác nhận, kể cả ở chế độ `auto`. Nếu cần, nâng mức quyền dần, đừng nhảy thẳng lên `full`.

## 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. Repo vẫn được cập nhật trong 3 tháng gần đây. Hệ sinh thái rộng: đội agent, bộ nhớ, console, bảo mật, theo dõi chi phí. Có chế độ kiểm soát quyền rõ ràng trong console. README cũng khá thẳng thắn về giới hạn, ví dụ nói bản demo dùng dữ liệu mẫu và không chứng minh swarm đã hoàn thành việc thật.

**Giới hạn.** Công cụ rất lớn: README nhắc tới 406 công cụ MCP và 61 lệnh CLI, nên người mới dễ choáng. Cách `init` thêm khá nhiều file vào dự án. Mod chạy với quyền tài khoản của bạn và không có sandbox. Một số tính năng học và bộ nhớ vẫn cần cấu hình embedding. Phần yêu cầu phần cứng và hệ điều hành, mình chưa thấy trong tư liệu.

**Khi nào chọn cách khác.** Nếu chỉ cần Claude Code làm vài việc nhỏ, bạn không cần lớp điều phối này. Nếu bạn là người làm văn phòng không viết code, Ruflo chưa phải công cụ dành cho bạn. Nếu muốn thử nhẹ nhàng, hãy bắt đầu bằng cách plugin (không thêm file vào dự án), hoặc thử trong một thư mục thử nghiệm trước khi đưa vào dự án thật.

## 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 trên Claude Code hoặc Codex, và chi phí dùng các dịch vụ đó vẫn theo tài khoản của bạn. README có plugin theo dõi token và chi phí để bạn kiểm soát.

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

Claude Code là công cụ viết code với mô hình. Ruflo là lớp harness bọc quanh nó, thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook và MCP server. Bạn vẫn dùng Claude Code như cũ, phần điều phối chạy ngầm sau khi `init`.

### Cần cài những gì trước?

Cần Node.js 20 trở lên vì `package.json` yêu cầu như vậy. Nếu dùng cách plugin thì cần Claude Code 2.1.287 trở lên. Các yêu cầu phần cứng hay hệ điều hành cụ thể thì tư liệu chưa nêu.

### Có dùng được với Codex không, hay chỉ Claude Code?

Dùng được với cả hai. Với Codex hoặc client MCP khác, bạn cấu hình command là `npx` và arguments là `-y`, `ruflo@latest`, `mcp`, `start`. README cũng nhắc tới Grok Build qua `npx ruflo init --grok`.

### Cài bằng init và cài bằng plugin khác nhau thế nào?

Cài bằng plugin không thêm file nào vào dự án nhưng chỉ có lệnh slash, vài skill và định nghĩa agent, không có hook. Cài bằng `npx ruflo init` thêm các thư mục như `.claude/` và `.claude-flow/` nhưng đem lại vòng lặp đầy đủ: agent, lệnh, skill, MCP server, hook, daemon.

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

Console có mức quyền read, write, manage, full và chế độ duyệt ask hoặc auto, mặc định là read + ask; thao tác mạng, chi tiêu, phá huỷ luôn cần xác nhận. Tuy nhiên README cảnh báo 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 mã trước khi cài. Chưa có thông tin chi tiết hơn về xử lý dữ liệu trong phần tư liệu mình có.

### Muốn xem giao diện mà không cần Claude Code thì làm sao?

Chạy `npx ruflo tui` để mở console độc lập trên terminal. Thêm `--plain` nếu muốn in ra một khung hình duy nhất cho script.
