# ruflo: điều phối nhiều 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. Nó thêm đội agent, bộ nhớ dùng lại giữa các phiên, hook và MCP server để AI làm việc có tổ chức hơn. Cài khá đơn giản: cần Node từ bản 20 trở lên và chạy một lệnh `npx ruflo@latest init` trong thư mục dự án.

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

Ruflo là một bộ khung (agent harness) chạy bao quanh Claude Code và Codex. Nó thêm cho AI các "công cụ làm việc": nhiều agent chuyên biệt, bộ nhớ giữ lại giữa các phiên, hook tự động và một MCP server. Nhờ vậy AI không chỉ trả lời từng câu hỏi lẻ mà làm việc theo nhóm, có kế hoạch. 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.

Vấn đề nó giải quyết khá quen thuộc. Bạn dùng Claude Code, giao một việc lớn, và AI dễ quên bối cảnh, làm từng bước rời rạc, mỗi phiên lại bắt đầu từ đầu. README của Ruflo mô tả bằng một công thức: Agent = Model + Harness. Model là phần viết code. Harness là phần cấp công cụ, bộ nhớ, vòng lặp và giới hạn để model làm được việc thật. Ruflo đóng vai harness đó.

Ai nên dùng? Lập trình viên đã quen Claude Code hoặc Codex và muốn giao những việc nhiều bước như rà soát repo, viết test, ghi lại thay đổi. Người mới cũng thử được vì README nhấn mạnh: sau `init` bạn cứ dùng Claude Code bình thường, phần phối hợp agent chạy ngầm. Điểm đáng giá nhất là cài chỉ bằng một lệnh, kèm một bảng điều khiển (console) để xem agent đang làm gì và tốn bao nhiêu token.

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

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

Theo README, Ruflo gom nhiều thứ vào một chỗ. Mình tóm lại theo lợi ích bạn nhận được.

- **Đội agent làm việc cùng nhau (swarm).** Thay vì một AI làm tất cả, nhiều agent chia việc và phối hợp. README ghi bản cài đầy đủ có 98 agent chuyên biệt. Bạn giao một việc lớn, các agent tự chia nhau.
- **Bộ nhớ qua các phiên.** Agent nhớ những gì đã làm và dùng lại kinh nghiệm từ các việc thành công trước đó. Bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code. README có nói thêm rằng phần học này cần embedding và các module học được cấu hình, không phải chạy hoàn toàn không cần gì.
- **Hook tự định tuyến.** Sau khi cài, hook tự chọn cách xử lý cho từng việc và ghi nhận mẫu làm việc hiệu quả. README nói bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI.
- **Bảng điều khiển cạnh Claude Code.** Console cho bạn theo dõi workflow, agent, model, token và chi phí. Bạn mở log của từng lần chạy, tìm kiếm, xem lại lỗi, so sánh các lần chạy. Mở bằng lệnh `/ruflo`.
- **Cho Claude lái console trong giới hạn bạn đặt.** Trong Settings → Claude control 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, tức Claude chỉ được xem và phải hỏi bạn. Các hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận, kể cả ở chế độ `auto`.
- **Hệ plugin lớn.** README liệt kê 48 plugin (cộng 3 plugin bên ngoài) 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-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 nói chuyện được với nhau. Đây là phần nâng cao, người mới chưa cần.

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

Chỉ liệt kê những gì tư liệu nói:

- **Node.js bản 20.0.0 trở lên.** Đây là yêu cầu ghi trong package.json của repo.
- **Claude Code** nếu bạn đi đường cài plugin. Cần Claude Code bản 2.1.287 trở lên. Muốn cài plugin từ terminal thì cần bản 2.1.292 trở lên.
- **Hoặc Codex / một MCP client khác.** README nói các client này dùng được bằng cách trỏ tới lệnh khởi động MCP server của Ruflo.
- **Giấy phép MIT**, ngôn ngữ chính là TypeScript.

Tư liệu không nói rõ về hệ điều hành, yêu cầu phần cứng hay API key riêng của Ruflo. Bạn vẫn cần tài khoản và quyền dùng Claude Code hoặc Codex như bình thường. Nếu muốn biết chi tiết hơn, xem README.md và thư mục docs trong repo.

```note
Một số mod chạy bằng đúng quyền tài khoản của bạn và không bị cô lập (sandbox). README khuyên đọc code trước khi cài. Với Claude control, hãy giữ mức mặc định read + ask cho đến khi bạn hiểu rõ nó làm gì.
```

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

README có hai đường cài với phạm vi rất khác nhau. Đường 1 (CLI, `npx ruflo@latest init`) cho đầy đủ: 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon. Nó thêm file vào dự án: `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và settings. Đường 2 (plugin Claude Code) nhẹ hơn: không thêm file nào vào dự án, chỉ có lệnh slash, vài skill và định nghĩa agent. README ghi đường CLI hợp với dùng thật, nên mình hướng dẫn đường này trước.

```steps
- Vào thư mục dự án | Mở terminal ngay trong thư mục dự án bạn muốn dùng
- 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 trong cùng thư mục để nó nhận cấu hình mới
- Giao việc thử | Đưa cho Claude Code một việc thật có nhắc tới swarm
- Mở bảng điều khiển | Gõ /ruflo để xem agent, token và chi phí
```

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

Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. `init` ghi file vào nơi bạn đang đứng, nên hãy `cd` vào đúng dự án trước. Ví dụ với một dự án đã có trên máy:

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

Thay `ten-thu-muc-du-an` bằng thư mục thật của bạn. Nếu bạn muốn lấy mã nguồn Ruflo về xem, dùng `git clone https://github.com/ruvnet/ruflo.git`, nhưng để dùng thì không cần, `npx` tự tải về.

### Chạy lệnh init

Đây là lệnh chính trong 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. Lệnh `init` thêm agent, hook, bộ nhớ và MCP server vào dự án. Nếu máy báo lỗi về Node, hãy kiểm tra bạn đã có Node 20 trở lên.

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 và giao việc thử

Mở Claude Code trong cùng thư mục. Claude Code sẽ nhận cấu hình của Ruflo ở lần khởi động tiếp theo, nên nếu đang mở sẵn, hãy đóng rồi mở lại. Sau đó thử một việc thật, 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.
```

Bạn có thể viết bằng tiếng Việt, nhưng mình giữ nguyên câu gốc của README để chắc chắn đúng cách gọi "ruflo swarm".

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

Nếu bạn không muốn thêm file vào dự án, hãy gõ lần lượt 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
```

Các lệnh này thêm kho plugin, cài lõi, bảng điều khiển và mod, nạp lại plugin rồi mở console. Nếu dùng Claude Code 2.1.292 trở lên, bạn cũng cài được từ terminal:

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

Còn muốn thêm plugin swarm hay bộ nhớ RAG, README có các lệnh `/plugin install ruflo-swarm@ruflo` và `/plugin install ruflo-rag-memory@ruflo`.

### 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 client, đặt **command** là `npx` và **arguments** như sau:

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

README còn nhắc lệnh này ở dạng viết liền: `npx -y ruflo@latest mcp start`. Cách điền cụ thể tuỳ từng client, bạn xem tài liệu của client đó.

### Chạy bảng điều khiển trong terminal thường

Console 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

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

- Sau `npx ruflo@latest init`, trong thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md`. Bạn mở thư mục ra xem là biết.
- Mở lại Claude Code rồi gõ `/ruflo`. Nếu bảng điều khiển hiện ra thì Ruflo đã được nhận.
- Nếu cài bằng plugin, gõ `/plugin` để xem `ruflo-console` và `ruflo-mods` có nằm trong dòng mod đang hoạt động không.
- Thử giao câu lệnh mẫu ở trên và xem Claude Code có nhắc tới swarm, agent hay không.
- Nếu dùng Codex, kiểm tra client đã liệt kê được các công cụ của MCP server `ruflo`. README chưa mô tả màn hình cụ thể ở bước này.

Tư liệu không nêu chuỗi thông báo thành công chính xác cho từng lệnh. Nếu bạn không chắc, xem hướng dẫn "First useful task" trong docs của repo.

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

Các tình huống dưới đây bám theo những khả năng README mô tả. Kết quả thực tế sẽ tuỳ dự án và model 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 dự án cũ, không ai nhớ module nào dễ hỏng. Hãy chạy `npx ruflo@latest init` trong thư mục dự án, mở lại Claude Code và dùng đúng 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 Code điều phối 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. Bạn nên đọc lại test và phần thay đổi trước khi chấp nhận.

### Trưởng nhóm tập làm quen với bảng điều khiển

Bạn muốn thấy AI đang làm gì thay vì chờ mù. README có kịch bản thử an toàn: vào `/ruflo`, chọn Settings → Claude control → write + ask, rồi nhờ Claude:

```text
Create a mission to add a dark mode toggle. Show me the mission and its status.
```

Claude mở trang Missions và đặt mục tiêu. Bạn xác nhận hành động tạo. Sau đó kiểm tra Missions có mục tiêu mới và Overview có 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 viết xong. Nút **Take back control** cho bạn thu hồi quyền ngay.

> Harness tốt không làm AI thông minh hơn, nó chỉ làm AI bớt quên và bạn bớt phải canh.
>
> — Ông T

### Quản lý chi phí khi dùng AI nhiều

Nếu bạn chạy nhiều agent, token tăng rất nhanh. Bảng điều khiển hiển thị token và chi phí cạnh Claude Code. README cũng có plugin `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí. Cài bằng `/plugin install` trong Claude Code theo đúng mẫu lệnh ở phần cài đặt, rồi mở `/ruflo` để theo dõi.

### Người dùng Codex muốn thêm bộ nhớ và công cụ

Bạn dùng Codex thay vì Claude Code. Hãy khai báo MCP server với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Codex sẽ gọi được các công cụ của Ruflo, trong đó có bộ nhớ. README không ghi chi tiết từng công cụ Codex nhìn thấy, nên bạn xem danh sách công cụ MCP trong client để biết chính xác.

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

Tư liệu không có mục xử lý sự cố riêng, nên các điểm dưới đây dựa trên yêu cầu ghi trong README và những lỗi rất dễ gặp với loại công cụ này.

- **Lệnh `npx` báo lỗi hoặc không chạy.** Kiểm tra bản Node bằng `node --version`. Repo yêu cầu Node 20 trở lên. Cập nhật Node rồi chạy lại.
- **Mở Claude Code nhưng không thấy gì mới.** Cấu hình chỉ được nhận ở lần khởi động tiếp theo. Hãy đóng hẳn Claude Code, mở lại đúng thư mục đã chạy `init`. Với plugin, chạy `/reload-plugins`.
- **Lệnh `/plugin install` không được.** Đường plugin cần Claude Code từ 2.1.287 trở lên. Lệnh cài từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước.
- **Bị thêm file lạ vào dự án.** Đó là hành vi của `init` (`.claude/`, `.claude-flow/`, `CLAUDE.md`…). Nếu không muốn, hãy dùng đường plugin, không thêm file nào. Bạn cũng nên chạy trong dự án có Git để dễ xem lại thay đổi.
- **Claude từ chối thao tác trong console.** Mức quyền mặc định là read + ask, nên hành động ghi hoặc quản lý sẽ bị từ chối. Đây là thiết kế an toàn. Nâng mức quyền trong Settings → Claude control nếu bạn chắc chắn, và đừng bật `auto` khi chưa quen.
- **Cài cùng một plugin ngoài từ hai kho.** 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 kho, nếu không mod và lệnh có thể bị nạp hai lần.

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

**Điểm mạnh.** Cài nhanh, chỉ một lệnh. Hỗ trợ cả Claude Code, Codex và các MCP client. Có bảng điều khiển để nhìn thấy agent, token, chi phí. Quyền của Claude trong console được chặn theo mức, mặc định thận trọng. 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 rộng: hàng chục plugin, hàng trăm công cụ MCP. Người mới dễ choáng, nên hãy bắt đầu chỉ với `init` rồi dùng như bình thường. README tự nói rõ nhiều phần là "khái niệm" chứ không phải bằng chứng thực thi, ví dụ các video demo dùng dữ liệu mẫu và không chứng minh swarm hoàn thành việc thật hay bộ nhớ gợi lại đúng. Đường `init` thêm khá nhiều file vào dự án. Mod chạy bằng quyền tài khoản bạn, không sandbox. Và chi phí token có thể tăng khi chạy nhiều agent cùng lúc.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần Claude Code chạy một việc nhỏ, dùng thẳng Claude Code là đủ, thêm harness chỉ làm phức tạp. Nếu bạn chỉ muốn thử vài lệnh, đường plugin sạch hơn. Nếu bạn cần cam kết về bảo mật dữ liệu hay hiệu năng cụ thể, README không đưa số liệu đủ để mình khẳng định, hãy tự thử trên một dự án nhỏ, không chứa dữ liệu nhạy cảm, trước khi dùng cho việc quan trọng.

## 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ã nguồn tự do. Tuy nhiên bạn vẫn cần quyền dùng Claude Code hoặc Codex, và chi phí của các dịch vụ AI đó nằm ngoài Ruflo. Tư liệu chưa nói chi tiết về giá của các dịch vụ này.

### Cài Ruflo bằng lệnh nào?

Trong thư mục dự án, chạy `npx ruflo@latest init`, rồi mở lại Claude Code trong cùng thư mục. Nếu muốn cài dạng plugin, không thêm file vào dự án, dùng `/plugin marketplace add ruvnet/ruflo` rồi `/plugin install ruflo-core@ruflo` trong Claude Code.

### Cần phiên bản Node hay Claude Code nào?

package.json yêu cầu Node 20.0.0 trở lên. Đường cài plugin cần Claude Code 2.1.287 trở lên, và lệnh cài plugin từ terminal cần 2.1.292 trở lên.

### Ruflo có dùng được với Codex 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 cụ thể tuỳ từng client.

### Claude có tự ý làm bậy trong bảng điều khiển được không?

Theo README, mức mặc định là read + ask, tức Claude chỉ được xem và phải hỏi bạn. Các hành động mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả ở chế độ auto. Nút Take back control cho bạn thu hồi quyền bất cứ lúc nào.

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

Tư liệu chưa có thông tin về 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 README và thư mục docs của repo, hoặc thử `npx ruflo@latest init` trên một dự án nhỏ.

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

Ruflo là lớp bao quanh Claude Code và Codex, thêm đội agent, bộ nhớ qua các phiên, hook tự định tuyến và bảng điều khiển. Claude Code thuần chỉ có công cụ gốc của nó. README cho biết Ruflo dành cho việc nhiều bước, còn việc nhỏ thì có thể không cần.
