# 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: lớp công cụ bọc quanh Claude Code và Codex để thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên và máy chủ MCP. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Dùng cơ bản không khó, nhưng hệ thống rất rộng nên nên bắt đầu từ một tác vụ nhỏ.

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

Ruflo là một "agent meta-harness" cho Claude Code và Codex: một lớp công cụ đặt quanh mô hình AI để nó có thêm agent chuyên biệt, bộ nhớ, vòng lặp tự cải thiện và các chốt kiểm soát. Tác giả mô tả ngắn gọn: mô hình là phần biết viết, còn harness là phần đưa cho mô hình công cụ, trí nhớ và luật chơi để nó làm việc được thật. Ruflo là phần harness đó. Dự án vốn có tên Claude Flow, nay đổi tên thành Ruflo, giấy phép MIT, hiện có khoảng 81.588 sao và 9.608 fork trên GitHub.

Bạn nên đọc bài này nếu đã dùng Claude Code (hoặc Codex) và thấy một agent đơn lẻ làm việc lớn hơi chật chội: quên ngữ cảnh giữa các phiên, không biết chia việc, khó theo dõi chi phí. Ruflo cho phép nhiều agent phối hợp thành một "swarm" (đàn agent), nhớ lại kinh nghiệm cũ và có bảng điều khiển để bạn nhìn thấy chuyện gì đang diễn ra.

Điểm đáng giá nhất là cách cài: một lệnh `npx ruflo@latest init` trong thư mục dự án, mở lại Claude Code là dùng được. 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 `init`, bạn cứ dùng Claude Code như bình thường, còn hệ thống hook sẽ 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) bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ dài hạn, hook và MCP server chỉ với một lệnh init.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những nhóm tính năng chính, theo đúng những gì README mô tả.

### Thêm agent, hook, bộ nhớ và MCP server vào dự án

Lệnh `init` bổ sung agent, hook, bộ nhớ và một MCP server vào thư mục dự án. Lợi ích thực tế: bạn không phải tự cấu hình từng thứ. Lần sau Claude Code khởi động, nó nhận ra các thành phần này luôn. README cho biết bản cài đầy đủ qua CLI gồm 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và một daemon chạy nền.

### Swarm: nhiều agent làm chung một việc

Thay vì một agent làm tuần tự, bạn có thể yêu cầu một swarm. Ví dụ trong README là cho swarm rà soát cả repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Với người làm dự án thật, đây là kiểu việc mà chia nhỏ cho nhiều agent sẽ gọn hơn.

### Bộ nhớ và học từ kinh nghiệm

Ruflo có bộ nhớ giữ lại giữa các phiên làm việc, và cơ chế học từ những tác vụ đã thành công để định tuyến tốt hơn lần sau. README lưu ý đây là một vòng học ở mức khái niệm: truy xuất vector cục bộ có thể chạy không cần LLM, nhưng vẫn cần embedding và các module học đã được cấu hình. Nghĩa là đừng kỳ vọng nó tự thông minh lên mà không cấu hình gì.

### Bảng điều khiển ngay cạnh Claude Code

Plugin `ruflo-console` là một "buồng lái": theo dõi workflow, agent, mô hình, token và chi phí cạnh Claude Code, mở log để xem, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Bạn mở nó bằng lệnh `/ruflo`. Có thể cho Claude điều khiển bảng này, nhưng bạn đặt giới hạn quyền (xem phần dùng thực tế bên dưới).

### Hệ sinh thái plugin

README liệt kê 48 plugin (cộng 3 plugin bên ngoài), chia nhóm: điều phối (swarm, autopilot, workflow, federation), bộ nhớ (agentdb, rag-memory, knowledge-graph), học tập, chất lượng mã (testgen, browser, docs, jujutsu), bảo mật (security-audit, aidefence), kiến trúc, DevOps (cost-tracker, observability) và mở rộng. Bạn chỉ cần cài thứ mình cần, ví dụ `ruflo-testgen` để tìm chỗ thiếu test và sinh test, hay `ruflo-cost-tracker` để theo dõi token và đặt ngân sách.

### Federation và các client khác

Với federation, agent trên các máy khác nhau có thể giao tiếp an toàn. Ngoài Claude Code, Codex và các MCP client khác cũng dùng được, chỉ cần trỏ tới `npx -y ruflo@latest mcp start`. README còn có tùy chọn `--grok` cho Grok Build.

## 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ừ 20.0.0 trở lên** (theo `package.json`). Bạn cần có `npx` đi kèm Node.
- **Claude Code** hoặc Codex (hay một MCP client khác) để dùng các agent.
- Nếu đi đường **plugin của Claude Code**: Claude Code phiên bản **2.1.287 trở lên**. Lệnh cài từ terminal (`claude plugin install ...`) cần bản **2.1.292 trở lên**.
- Tài khoản và quyền truy cập của chính công cụ AI bạn dùng (Claude Code, Codex).

README phần được cung cấp không nói gì về yêu cầu GPU, dung lượng ổ đĩa hay hệ điều hành cụ thể, nên mình không khẳng định. Phần plugin có nhắc tới các plugin tùy chọn như chạy LLM cục bộ hoặc tìm kiếm tăng tốc GPU, nhưng đó là phần thêm, không phải điều kiện để bắt đầu.

```note
Các mod trong Ruflo chạy với quyền tài khoản của bạn và không bị đặt trong hộp cát (sandbox). README khuyên đọc mã của mod trước khi cài. Hãy thử trên một dự án không chứa dữ liệu nhạy cảm trước.
```

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

```steps
- Mở terminal đúng thư mục | Vào 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
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thật | Dán một câu lệnh mẫu để thử swarm
- (Tùy chọn) Cài plugin hoặc bảng điều khiển | Dùng /plugin để thêm console và mod
```

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

Đây là chỗ người mới hay vấp nhất: `init` ghi file vào thư mục bạn đang đứng. Nếu bạn mở terminal ở sai chỗ (ví dụ thư mục người dùng), nó sẽ thêm file vào đó. Hãy `cd` vào dự án trước. Tên thư mục dưới đây chỉ là ví dụ:

```bash
cd ten-thu-muc-du-an
```

Trên Windows bạn có thể dùng PowerShell hoặc Git Bash, lệnh `cd` giống nhau.

### 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 Ruflo mới nhất mà không cần cài toàn cục. Lệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh của README, nó tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và file 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 khác biệt sau khi chạy.

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

### Mở lại Claude Code

Mở Claude Code ngay trong 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ên nếu bạn đang mở sẵn thì hãy thoát ra và mở lại.

### Giao một tác vụ thật

Dán câu lệnh mẫu của README vào Claude Code:

```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 bằng tiếng Việt, ý chính là yêu cầu "dùng ruflo swarm" cho việc đó.

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

Nếu bạn không muốn thêm file nào vào dự án, README có đường "plugin". Cần Claude Code từ 2.1.287 trở lên. Chạy 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
```

Các dòng này gõ trong khung chat của Claude Code, không phải trong terminal thường. Đường này không để lại file nào trong dự án. Đổi lại, README nói nó chỉ cho lệnh slash, vài skill và định nghĩa agent, không có hook. Muốn dùng đủ vòng lặp như tài liệu mô tả thì dùng `init`.

Từ terminal, trên Claude Code 2.1.292 trở lên:

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

### Dùng với Codex hoặc MCP client khác

Không cần thiết lập dự án: cấu hình lệnh (command) là `npx` với các đối số (arguments):

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

Cách điền cụ thể tùy từng client, README không hướng dẫn chi tiết cho từng phần mềm. Bạn xem tài liệu của client mình dùng để biết chỗ nhập command và arguments.

### Chạy bảng điều khiển 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 một khung hình duy nhất, tiện cho script.

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

Cách kiểm tra theo tư liệu:

1. Sau `init`, thư mục dự án có thêm các mục như `.claude/`, `.claude-flow/` và file `CLAUDE.md`.
2. Mở lại Claude Code, gõ `/ruflo`. Với đường cài plugin, mở `/plugin` và xem `ruflo-console`, `ruflo-mods` có xuất hiện trong dòng mod đang hoạt động hay không.
3. Thử câu lệnh swarm mẫu ở trên và xem Claude Code có điều phối agent, viết test và tóm tắt thay đổi không.
4. Với bảng điều khiển, thử `npx ruflo tui` để thấy giao diện chạy được trong terminal.

README không nêu một dòng "thành công" cố định để đối chiếu, nên tiêu chí thực tế là: lệnh `init` không báo lỗi, `/ruflo` mở được và Claude Code nhận ra công cụ mới.

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

Các tình huống dưới đây bám vào những khả năng được README nêu. Kết quả cụ thể sẽ tùy dự án và mô hình bạn dùng.

### Lập trình viên: rà soát một repo lạ

Bạn vừa nhận một repo từ đồng nghiệp và chưa biết phần nào dễ hỏng. Mở Claude Code trong repo đó (đã chạy `init`) và nhập:

```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: swarm chỉ ra module rủi ro nhất, viết test cho nó và đưa bản tóm tắt thay đổi. Bạn đọc lại test, chạy thử và quyết định có giữ hay không. Đừng bỏ qua bước xem lại này.

> Đừng học hết 406 công cụ: chạy init, rồi cứ dùng Claude Code như bình thường.
>
> — Ông T

### Người quản lý dự án: theo dõi agent và chi phí

Bạn muốn biết agent đang làm gì và tốn bao nhiêu token. Cài `ruflo-console` (xem phần cài đặt), mở `/ruflo` để xem workflow, agent, mô hình, token và chi phí cạnh Claude Code. Muốn thêm kiểm soát ngân sách thì README có plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí). Bạn mở danh mục plugin bằng `/ruflo market` để cài, bật, tắt và cập nhật, mỗi thao tác đều hỏi xác nhận trước.

### Người mới: để Claude tạo một "mission" trong bảng điều khiển

Đây là bài thử an toàn mà README mô tả từng bước:

1. Cài console, mở `/ruflo`, vào **Settings → Claude control** và chọn **write + ask**.
2. Nhập 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 xác nhận hành động tạo trong console.
4. Kiểm tra mục Missions có mục tiêu đó và mục Overview ghi lại hành động.
5. Muốn dừng, bấm **Take back control**.

Hai điều cần nhớ. Một: mức mặc định hiện là **read + ask**, các mức quyền là `read`, `write`, `manage`, `full`, và các hành động mạng, chi tiêu hay phá hủy luôn cần xác nhận kể cả khi bạn chọn `auto`. Hai: tạo mission không có nghĩa tính năng đã được viết xong.

### Dev nhóm nhỏ: sinh test và kiểm tra bảo mật bằng plugin

Bạn có một dự án lâu năm thiếu test. Cài plugin theo cách README hướng dẫn, ví dụ:

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

README mô tả plugin này là "tìm test còn thiếu và sinh tự động". Tương tự, `ruflo-security-audit` quét lỗ hổng và CVE, còn `ruflo-aidefence` chặn prompt injection và phát hiện dữ liệu cá nhân. Hãy cài từng plugin một, thử trên nhánh riêng và đọc kỹ kết quả trước khi gộp vào nhánh chính.

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

### Chạy `npx` báo lỗi hoặc không chạy

Phiên bản Node quá cũ là nguyên nhân dễ gặp nhất, vì `package.json` yêu cầu Node 20 trở lên. Kiểm tra bằng `node --version`. Nếu thấp hơn 20, hãy nâng cấp Node rồi chạy lại.

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

README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp sau `init`. Hãy thoát hẳn rồi mở lại, và chắc chắn bạn mở Claude Code đúng trong thư mục đã chạy `init`. Với đường plugin, chạy `/reload-plugins`.

### Lệnh `/plugin` hoặc `claude plugin install` không hoạt động

Đường plugin cần Claude Code 2.1.287 trở lên, còn lệnh cài từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code nếu bản của bạn thấp hơn.

### Cài một plugin hai lần, lệnh bị nạp trùng

README cảnh báo với các plugin bên ngoài (như `agentic-qe-fleet`, `agentdb`, `agentic-flow`): chỉ cài từ một marketplace, hoặc marketplace gốc của chúng, hoặc `ruflo`. Nếu bật từ cả hai, mod và lệnh sẽ nạp hai lần. Hãy gỡ một bên.

### Claude từ chối thao tác trong bảng điều khiển

Đây thường không phải lỗi mà là cơ chế an toàn: thao tác vượt quá mức quyền bạn đặt sẽ bị từ chối. Nếu bạn đã bấm **Take back control**, các lệnh sau đó cũng bị từ chối cho đến khi bạn trả quyền lại. Muốn cho phép thì nâng mức quyền một cách có chủ đích trong Settings → Claude control, và nhớ rằng thao tác mạng, chi tiêu, phá hủy vẫn cần bạn xác nhận.

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

**Điểm mạnh.** Cài đặt nhanh (một lệnh), giấy phép MIT, dự án vẫn được cập nhật trong vài tháng gần đây và có cộng đồng lớn. Bạn có thể chọn mức "nhẹ" (chỉ plugin, không file trong dự án) hoặc mức "đầy đủ" (init). Cơ chế quyền `read / write / manage / full` kèm `ask / auto` cho bạn quyền kiểm soát rõ ràng. Thêm vào đó là bảng điều khiển để nhìn thấy agent, token và chi phí.

**Giới hạn.** Hệ thống rất rộng: hàng chục plugin, hàng trăm công cụ. Người mới dễ choáng, nên bắt đầu từ một tác vụ nhỏ. README tự nói rõ một số thứ chỉ là minh họa: hoạt ảnh workflow dùng dữ liệu mẫu, và vòng học là mô hình khái niệm, không phải bằng chứng cho mọi kết quả. Phần README mình có cũng chưa nói về hiệu quả đo được so với dùng Claude Code đơn thuần, nên mình không khẳng định nó luôn làm nhanh hơn hay rẻ hơn. Nhiều agent chạy song song còn có thể tốn token hơn, vì vậy hãy theo dõi chi phí.

**Khi nên chọn cách khác.** Nếu việc của bạn là sửa vài file nhỏ, một phiên Claude Code thường là đủ và đơn giản hơn. Nếu bạn không muốn thêm file như `.claude/` và `CLAUDE.md` vào dự án, hãy dùng đường plugin hoặc chỉ chạy MCP server. Nếu dữ liệu rất nhạy cảm, hãy đọc kỹ mã của mod và cấu hình quyền trước khi dùng, vì mod chạy với quyền tài khoản của bạn.

## 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, sửa và phân phối được. 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í token của các dịch vụ đó vẫn do bạn chịu. Tư liệu không nêu mức giá cụ thể.

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

Claude Code là công cụ để mô hình làm việc, còn Ruflo là lớp harness bọc quanh nó. Ruflo thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên, hook, MCP server và bảng điều khiển. Tư liệu chưa có số liệu so sánh hiệu quả giữa hai cách.

### Cần cài gì trước khi dùng Ruflo?

Bạn cần Node.js từ 20.0.0 trở lên để chạy `npx`. Nếu cài qua plugin thì cần Claude Code từ 2.1.287 trở lên (lệnh `claude plugin install` cần 2.1.292 trở lên). Tư liệu không nêu yêu cầu GPU.

### 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 MCP client khác dùng được bằng cách cấu hình command là `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Cách điền chi tiết phụ thuộc vào từng phần mềm client.

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

Tư liệu mình có không nêu rõ hệ điều hành được hỗ trợ. Ruflo chạy qua Node và `npx`, nên nếu máy bạn có Node 20 trở lên thì có thể thử, nhưng mình không thể khẳng định mọi tính năng đều chạy tốt trên Windows.

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

Có nếu dùng `npx ruflo@latest init`: nó thêm các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings. Nếu không muốn, hãy dùng đường cài plugin, README ghi là không thêm file nào vào dự án.

### Có an toàn khi cho Claude điều khiển bảng điều khiển không?

README cho bạn đặt mức quyền (read, write, manage, full) và chế độ ask hoặc auto, mặc định là read + ask. Hành động mạng, chi tiêu và phá hủy vẫn cần xác nhận kể cả khi ở chế độ auto, và bạn có thể bấm Take back control để dừng. Riêng các mod thì chạy với quyền tài khoản của bạn và không bị sandbox, nên cần đọc mã trước.
