# 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 agent harness: lớp công cụ bao quanh Claude Code và Codex để chạy nhiều agent phối hợp, có bộ nhớ qua các phiên làm việc. Cài chỉ cần một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node từ 20 trở lên. Sau đó bạn cứ dùng Claude Code bình thường.

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

Ruflo là một "agent harness" — lớp công cụ đặt quanh Claude Code và Codex để các AI agent không chỉ chạy lẻ tẻ mà biết phối hợp thành đội, nhớ việc đã làm và có giới hạn an toàn. Repo này trước đây tên Claude Flow, hiện hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, dùng giấy phép MIT.

Nếu bạn đã dùng Claude Code và thấy nó hay quên ngữ cảnh giữa các phiên, hoặc muốn giao một việc lớn cho nhiều agent cùng làm, thì Ruflo dành cho bạn. Tác giả mô tả ngắn gọn: mô hình AI là người viết, còn harness là bàn làm việc gồm công cụ, bộ nhớ, vòng lặp và các điều khiển để mô hình làm việc được thật.

Điểm đáng giá nhất là cách cài rất gọn: một lệnh `npx ruflo@latest init` trong thư mục dự án, rồi mở Claude Code 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; sau khi `init`, hệ thống hook tự định tuyến tác vụ và điều phối agent ở phía sau.

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

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

Dưới đây là những phần chính, theo cách hiểu thực tế cho người mới.

- **Đội agent (swarm):** README nói Ruflo bổ sung hơn 100 agent chuyên biệt và cho chúng tự tổ chức thành nhóm. Lợi ích: một việc lớn như rà soát cả repo có thể chia cho nhiều agent thay vì một agent làm tuần tự.
- **Bộ nhớ qua nhiều phiên:** agent nhớ được kinh nghiệm từ các tác vụ trước. Bạn đỡ phải giải thích lại bối cảnh mỗi lần mở Claude Code.
- **Hook tự định tuyến:** sau `init`, bạn dùng Claude Code bình thường, còn hook tự chọn cách xử lý và học từ các mẫu làm việc thành công.
- **MCP server:** Ruflo đi kèm một MCP server, nên Codex hoặc các MCP client khác cũng kết nối được.
- **Bảng điều khiển (console):** một "buồng lái" cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí, xem log, tìm lỗi, phát lại và so sánh các lần chạy. Mở bằng lệnh `/ruflo` trong Claude Code.
- **Claude điều khiển console có giới hạn:** bạn chọn mức quyền `read`, `write`, `manage` hoặc `full`, và 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 xác nhận, kể cả ở chế độ `auto`.
- **Hệ 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, chất lượng mã và kiểm thử, bảo mật, kiến trúc, DevOps, mở rộng. Ví dụ `ruflo-testgen` tìm test còn thiếu và tạo test, `ruflo-cost-tracker` theo dõi token và cảnh báo chi phí, `ruflo-security-audit` quét lỗ hổng.
- **Liên kết nhiều máy (federation):** agent trên các máy khác nhau có thể trao đổi an toàn. Đây là tính năng nâng cao, người mới chưa cần đụng tới.

Trong số đó, phần bạn nên thử trước là đội agent, bộ nhớ và console. Còn lại cứ để đó khi cần mới tìm hiểu.

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

Theo tư liệu repo, bạn cần:

- **Node.js từ phiên bản 20.0.0 trở lên** (package.json yêu cầu `>=20.0.0`). Cần có `npx` đi kèm Node.
- **Claude Code** nếu bạn muốn dùng đường cài chính. Riêng đường cài chỉ bằng plugin cần 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` (lệnh này thêm file vào dự án).
- Tài khoản và API key cho Claude Code hoặc Codex: tư liệu ở đây chưa nói chi tiết, bạn dùng theo cách bạn đang dùng các công cụ đó.

README phần đã cung cấp chưa nêu rõ hệ điều hành hỗ trợ hay yêu cầu phần cứng như GPU. Cần chắc chắn thì xem tiếp README và thư mục `docs/` trong repo.

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

Có ba đường cài. Đường chính nhanh nhất là `init`; hai đường còn lại dành cho trường hợp đặc biệt.

```steps
- Mở terminal trong dự án | Vào đúng thư mục dự án bạn muốn dùng Ruflo
- Chạy init | Gõ npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- 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
- Giao thử một việc thật | Dán câu lệnh mẫu để Claude dùng swarm
- (Tuỳ chọn) Mở console | Gõ /ruflo trong Claude Code
```

### 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 dự án. Chỗ này người mới hay vấp: mở terminal ở thư mục khác thì Ruflo sẽ cài sai chỗ.

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

Đây chỉ là lệnh `cd` thông thường. Hãy thay phần sau `cd` bằng đường dẫn thật của dự án 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 Ruflo bản mới nhất mà 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. Phần so sánh trong README nói đường này tạo các file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng một số file hỗ trợ và settings. Vì vậy nếu dự án nằm trong git, bạn nên commit trước để dễ xem Ruflo đã thêm gì.

Nếu 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 và giao việc

Mở (hoặc mở lại) 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 kế tiếp. Rồi thử một câu như 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.
```

Câu này nhờ Claude dùng một swarm để rà soát repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi.

### 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 và cần Claude Code 2.1.287 trở lên. Gõ từng dòng 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ũng có thể cài từ terminal:

```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à README nói chúng không được cách ly (sandbox). Hãy đọc mã nguồn trước khi cài.
```

README cũng nói đường plugin chỉ cho lệnh slash và vài skill, không có hook; muốn dùng đầy đủ như tài liệu mô tả thì chọn đường `init`.

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

Không cần cài vào dự án. Trong phần cấu hình MCP của công cụ, đặt **command** là `npx` và **arguments** như sau:

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

Nghĩa là công cụ của bạn sẽ chạy `npx -y ruflo@latest mcp start` để khởi động MCP server của Ruflo.

### 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 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:

1. Sau `init` và khởi động lại Claude Code, thư mục dự án xuất hiện các file/thư mục mới như `.claude/` và `.claude-flow/`.
2. Gõ `/ruflo` trong Claude Code sẽ mở console (nếu bạn đã cài `ruflo-console`).
3. Với đường plugin, mở `/plugin` và xem plugin có hiện trong dòng "active mods" không.
4. Có thể chạy `npx ruflo tui` để thấy console chạy riêng trong terminal.
5. Thử bài "tạo mission" trong README: vào Settings → Claude control → write + ask, rồi nhờ Claude "Create a mission to add a dark mode toggle. Show me the mission and its status." Xác nhận hành động tạo, rồi kiểm tra mục Missions và Overview. Lưu ý: tạo mission không có nghĩa là tính năng đã được viết xong.

README chưa nêu một dòng "thành công" cố định cho lệnh `init`, nên cách chắc nhất là kiểm tra các dấu hiệu trên.

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

Tư liệu cho thấy Ruflo mạnh nhất ở việc điều phối nhiều bước. Dưới đây là các tình huống bám đúng khả năng được mô tả.

### Lập trình viên mới: rà soát dự án thừa kế

Bạn vừa nhận một dự án của người khác và không biết bắt đầu từ đâu. Sau khi `init` và mở lại Claude Code, dán 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 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 trước khi tin.

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

### Chủ dự án nhỏ: theo dõi chi phí và việc agent đang làm

Bạn giao việc cho agent nhưng sợ tốn token mà không biết. Cài `ruflo-console` rồi gõ `/ruflo` để xem workflow, agent, model, token và chi phí cạnh Claude Code. Bạn còn có thể cài `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí.

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

Kết quả: bạn thấy được mỗi lần chạy tốn bao nhiêu và lần nào lỗi, thay vì chờ hóa đơn cuối tháng.

### Nhân viên kỹ thuật: bổ sung test còn thiếu

Công ty có mã nguồn nhưng ít test. Plugin `ruflo-testgen` theo README tìm test còn thiếu và tạo chúng tự động.

```text
/plugin install ruflo-testgen@ruflo
```

Sau đó nhờ Claude nêu rõ thư mục cần kiểm tra. Kết quả là một bộ test nháp để bạn xem lại, không phải bản cuối cùng.

### Người dùng Codex: gắn Ruflo như một MCP server

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"]` như phần cài đặt ở trên. Khi đó công cụ của bạn gọi được các công cụ của Ruflo mà không phải thêm file vào dự án.

```note
Hãy bắt đầu với mức quyền mặc định read + ask của console. Chỉ nâng lên write, manage hay full khi bạn đã hiểu Claude sẽ làm gì. Mọi hành động tốn tiền, đụng mạng hoặc phá hủy vẫn cần bạn xác nhận.
```

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

Tư liệu không có mục xử lý lỗi riêng, nên dưới đây là các tình huống rất dễ gặp với loại công cụ này.

**1. Lệnh `npx` báo lỗi hoặc không chạy.** Thường do Node quá cũ. Kiểm tra bằng `node --version`; package.json yêu cầu từ 20.0.0 trở lên. Nếu thấp hơn, cập nhật Node rồi chạy lại.

**2. Claude Code không thấy Ruflo sau `init`.** README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy đóng hẳn Claude Code, mở lại trong đúng thư mục bạn vừa chạy `init`.

**3. Lệnh `/plugin` không chạy hoặc báo phiên bản.** Đườ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). Cập nhật Claude Code hoặc chuyển sang đường `init`. Sau khi cài plugin, nhớ gõ `/reload-plugins`.

**4. Plugin cài rồi mà thiếu tính năng.** Theo README, đường plugin chỉ cho lệnh slash, vài skill và định nghĩa agent; hook và hầu hết MCP server thì không có. Muốn đầy đủ, dùng `npx ruflo@latest init`.

**5. Một plugin ngoài bị tải hai lần.** README cảnh báo với `agentic-qe-fleet`, `agentdb`, `agentic-flow`: chỉ cài từ một marketplace duy nhất, vì cài từ cả hai thì mod và lệnh bị nạp hai lần.

**6. Claude từ chối hành động trong console.** Rất có thể mức quyền của bạn đang thấp hơn hành động đó. README nói hành động vượt mức quyền sẽ bị từ chối. Nâng mức quyền có chủ ý, hoặc bấm Take back control nếu muốn dừng.

## 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.
- Gộp nhiều thứ vào một chỗ: agent, bộ nhớ, hook, MCP server, console theo dõi chi phí.
- Có cơ chế kiểm soát rõ ràng: mức quyền, chế độ duyệt, nút lấy lại quyền điều khiển.
- Dùng được với Claude Code, Codex và các MCP client khác.

**Giới hạn cần biết:**

- Bề mặt rất rộng (hàng chục plugin, hàng trăm công cụ). Người mới dễ choáng; hãy chỉ dùng vài thứ cần thiết.
- `init` thêm nhiều file vào dự án. Hãy commit trước khi chạy để dễ hoàn tác.
- Các mod không được sandbox và chạy với quyền tài khoản của bạn.
- README tự nói phần học và bộ nhớ ở mức "khái niệm", và một số bản demo dùng dữ liệu mẫu nên không chứng minh việc swarm đã hoàn thành. Hãy kiểm chứng kết quả thật.
- Thông tin về hệ điều hành, phần cứng, chi phí token chưa rõ trong tư liệu.

**Khi nên chọn cách khác:** nếu bạn chỉ cần Claude Code làm các việc đơn giản trong một file, dùng Claude Code thuần là đủ và nhẹ hơn. Ruflo đáng thử khi bạn có việc nhiều bước, muốn agent nhớ qua các phiên và muốn theo dõi chi phí tập trung. Bắt đầu bằng một dự án thử, đọc kỹ những gì `init` đã thêm, rồi mới mở rộng.

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

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

Mã nguồn dùng giấy phép MIT nên dùng được miễn phí. Tuy nhiên Ruflo chạy trên Claude Code, Codex hoặc nhà cung cấp mô hình khác, và chi phí đó tính riêng theo gói của bạn. Tư liệu chưa nêu mức chi phí cụ thể.

### Cài Ruflo cần những gì?

Cần Node.js từ phiên bản 20.0.0 trở lên theo package.json. Đường cài chính là chạy `npx ruflo@latest init` trong thư mục dự án. Nếu chỉ cài plugin trong Claude Code thì cần Claude Code từ 2.1.287 trở lên.

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

Tư liệu cung cấp chưa nêu yêu cầu GPU cho đường cài cơ bản. README có nhắc một plugin riêng (ruflo-ruvector) liên quan tìm kiếm tăng tốc GPU, nhưng đó là tuỳ chọn. Bạn nên xem README đầy đủ nếu định dùng tính năng đó.

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

README phần được cung cấp chưa ghi rõ hệ điều hành hỗ trợ. Lệnh chính là `npx` nên chạy được ở nơi có Node 20 trở lên, nhưng bạn nên xem README và thư mục docs/ trong repo để chắc chắn.

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

Ruflo bổ sung một lớp harness quanh Claude Code: hơn 100 agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook định tuyến và console theo dõi. Claude Code thuần không có sẵn các phần này. Đổi lại, Ruflo thêm nhiều file vào dự án và phức tạp hơn.

### Dùng Ruflo có an toàn không, Claude có tự làm bậy được không?

Console cho bạn chọn mức quyền read, write, manage hoặc full và chế độ ask hoặc auto; mặc định hiện là read + ask. Hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần xác nhận kể cả ở chế độ auto. Riêng các mod không được sandbox và chạy với quyền tài khoản của bạn, nên cần đọc mã trước khi cài.

### Tôi dùng Codex thì có dùng được Ruflo không?

Có. README nói Codex và các MCP client khác dùng được bằng cách cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Cách này không cần thêm file vào dự án.
