# 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à lớp điều phối bao quanh Claude Code và Codex: thêm nhiều agent chuyên biệt, swarm, bộ nhớ qua các phiên và một MCP server. Cài chỉ cần một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Người mới có thể dùng ngay mà không cần học hết các lệnh.

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

ruflo là một “agent meta-harness” cho Claude Code và Codex. Nói đơn giản: Claude Code là bộ não biết viết code, còn ruflo là bộ đồ nghề quanh nó. Bộ đồ nghề này gồm agent chuyên biệt, bộ nhớ giữ lại giữa các phiên làm việc, hook tự động và một MCP server. Nhờ vậy Claude không chỉ chạy một mình mà có thể phối hợp nhiều agent thành một đội.

Repo này ban đầu có tên Claude Flow, do Reuven Cohen (rUv) làm ra, nay đổi tên thành ruflo. Hiện có khoảng 81.588 sao và 9.608 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript, và vẫn được cập nhật trong vài tháng gần đây. Bạn nên dùng nó nếu đã dùng Claude Code (hoặc Codex) và muốn giao những việc lớn hơn một câu lệnh: rà soát cả repo, viết test, theo dõi tiế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, mở lại Claude Code, rồi cứ làm việc bình thường. README nói rõ bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Sau khi `init`, hệ thống hook tự định tuyến tác vụ và phối hợp 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.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những phần chính mà README mô tả, kèm lợi ích thực tế.

- **Nhiều agent chuyên biệt và swarm.** README nói có hơn 100 agent chuyên biệt. Chúng được tổ chức thành “swarm” để chia việc cho nhau. Với bạn, đó là cách giao một việc lớn mà không phải tự chia nhỏ từng bước.
- **Bộ nhớ qua các phiên.** Agent nhớ được kinh nghiệm từ các tác vụ trước. README mô tả đây là một vòng học: bộ nhớ đưa kinh nghiệm hữu ích quay lại để định tuyến tốt hơn. Lưu ý README ghi đây là mô hình khái niệm, và phần học dùng embedding cùng các module học đã cấu hình.
- **Hook tự động.** Sau `init`, hook tự định tuyến tác vụ và học từ các mẫu làm thành công, bạn không phải gọi từng thứ.
- **MCP server.** Codex và các client MCP khác có thể trỏ vào ruflo để dùng chung bộ công cụ.
- **Bảng điều khiển (console) trong Claude Code.** Bạn theo dõi workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Có thể mở lại log và kết quả của từng lần chạy để tìm kiếm, xem lỗi, phát lại và so sánh.
- **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 chạm mạng, tốn tiền hoặc phá hủy vẫn cần bạn xác nhận kể cả khi để `auto`.
- **Hệ plugin lớn.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài). Có nhóm điều phối, bộ nhớ, kiểm thử, bảo mật, theo dõi chi phí… Ví dụ `ruflo-testgen` tìm test còn thiếu 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 (federation).** Agent ở các máy khác nhau có thể trao đổi với nhau một cách bảo mật. Mảng này dành cho nhu cầu nâng cao, người mới chưa cần đụng tới.

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

Theo tư liệu, bạn cần những thứ sau:

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json`. Gói npm của dự án có tên `claude-flow` và có lệnh CLI.
- **Claude Code** (hoặc Codex / một client MCP khác). Nếu muốn cài theo đường plugin của Claude Code thì cần Claude Code bản **2.1.287 trở lên**. Lệnh `claude plugin install` chạy từ terminal cần bản **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy `init`, vì lệnh này thêm file vào chính thư mục đó.

Tư liệu không nói rõ về hệ điều hành, phần cứng hay API key cụ thể. Phần liên kết với dịch vụ AI bên ngoài sẽ phụ thuộc vào cấu hình của bạn. Nếu bạn dùng Claude Code thì tài khoản Claude của bạn vẫn là thứ chạy mô hình.

```note
Các “mod” trong ruflo chạy với quyền của tài khoản bạn và không được cô lập (sandbox). README khuyên đọc mã trước khi cài. Hãy giữ chế độ Claude control ở mức thấp (read + ask) cho đến khi bạn quen.
```

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

```steps
- Mở terminal đúng thư mục | vào thư mục dự án mà bạn muốn dùng ruflo
- 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 một việc thật | nhập một yêu cầu cụ thể cho swarm
- (Tuỳ chọn) Cài bảng điều khiển | dùng plugin trong Claude Code rồi gõ /ruflo
```

### 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 thư mục dự án. Chỗ này người mới hay vấp: nếu mở terminal ở thư mục khác, ruflo sẽ cài sai chỗ. Nếu chưa có dự án, bạn có thể tải một repo về rồi vào thư mục đó. Dưới đây chỉ là ví dụ chung, bạn thay `<tên-tài-khoản>/<tên-repo>` bằng repo của mình:

```bash
git clone https://github.com/<tên-tài-khoản>/<tên-repo>.git
cd <tên-repo>
```

### Chạy lệnh init

Đây là lệnh cài chính của README. `npx` tải và chạy ruflo bản mới nhất mà không cần cài toàn cục:

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

Lệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo README, với cách cài này bạn sẽ thấy các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và file settings xuất hiện trong dự án. Nếu bạn dùng Git, đây là lúc nên xem những thay đổi này trước khi commit.

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

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

### Mở lại Claude Code và giao việc

Mở Claude Code trong cùng thư mục. 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 đang mở sẵn thì hãy tắt rồi mở lại. Sau đó thử một yêu cầu thật, đúng như ví dụ 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.
```

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

Nếu bạn không muốn thêm file vào dự án, README có đường cài plugin. Đường này cài công cụ lõi, bảng điều khiển và các mod, không thêm file nào vào dự án. Chạy ngay trong Claude Code (bản 2.1.287 trở lên):

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo
```

Từ terminal, trên Claude Code 2.1.292 trở lên, README cho lệnh:

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

So sánh nhanh theo README: đường plugin nhẹ hơn, chủ yếu là lệnh gạch chéo và định nghĩa agent, không cài hook. Đường `npx ruflo@latest init` mới là đầy đủ (agent, lệnh, skill, MCP server, hook, daemon) và README khuyên dùng cho việc nghiêm túc.

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

Với Codex hay client MCP khác, bạn cấu hình **command** là `npx` và **arguments** như sau:

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

Hoặc nếu client nhận một dòng lệnh duy nhất, README ghi lệnh tương đương:

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

Bạn cũng có thể chạy bảng điều khiển riêng ngoài Claude Code, thêm `--plain` nếu muốn in một khung cho script:

```bash
npx ruflo tui
```

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

README không ghi một lệnh “kiểm tra sức khỏe” riêng cho đường `init`, nên mình chỉ nêu những dấu hiệu có trong tư liệu:

1. Sau `npx ruflo@latest init`, trong thư mục dự án xuất hiện các thư mục/file như `.claude/`, `.claude-flow/` và `CLAUDE.md`.
2. Mở lại Claude Code rồi gõ `/ruflo`. Nếu bảng điều khiển hiện ra thì phần console đã hoạt động.
3. Nếu cài bằng plugin, mở `/plugin` và kiểm tra các mod có xuất hiện trong dòng “active mods”.
4. Cách chắc nhất là giao yêu cầu mẫu ở trên và xem Claude Code có phối hợp agent để xử lý hay không.

Nếu cần chi tiết hơn, hãy xem thư mục `docs/` trong repo, nơi README trỏ tới hướng dẫn người dùng và hướng dẫn từng tính năng.

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

Các tình huống dưới đây bám theo khả năng và ví dụ có trong README.

### Dev mới: rà soát cả repo trước khi sửa

Bạn vừa nhận một dự án lạ và không biết đụng vào đâu. Sau khi cài xong, mở Claude Code trong thư mục dự án và gõ đúng yêu cầu mẫu:

```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 chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn vẫn nên tự đọc lại phần test và diff trước khi giữ lại.

> Bạn không cần học hết hàng trăm công cụ. Cài xong, cứ giao việc cho Claude Code như bình thường.
>
> — Ông T

### Người làm sản phẩm: tạo “mission” và theo dõi trên bảng điều khiển

Bạn muốn theo dõi một mục tiêu mà không phải đọc log dài. README có kịch bản mẫu. Cài console, gõ `/ruflo`, rồi vào Settings → Claude control và chọn **write + ask**. Sau đó yêu cầu:

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

Claude sẽ mở mục Missions và đặt mục tiêu. Bạn xác nhận thao tác tạo, rồi kiểm tra trong Missions và mục Overview. Chú ý: README nhấn mạnh tạo mission không có nghĩa là tính năng đã được làm xong. Nếu muốn dừng, bấm **Take back control**, các công cụ console của Claude sẽ bị từ chối cho đến khi bạn trả quyền lại.

### Người dùng Codex: dùng chung bộ công cụ qua MCP

Bạn dùng Codex chứ không phải Claude Code. Bạn thêm một MCP server vào cấu hình của client với command `npx` và arguments như ở phần cài đặt. Client sẽ gọi ruflo như một MCP server. Tư liệu không nêu chi tiết cách mỗi client khai báo cấu hình, nên hãy xem tài liệu của client đó để biết chỗ dán.

### Chủ dự án nhỏ: kiểm soát chi phí và chất lượng bằng plugin

Nếu bạn lo token tốn quá tay hoặc test còn thiếu, có thể cài thêm plugin từng phần từ marketplace, ví dụ:

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

README mô tả `ruflo-cost-tracker` theo dõi token, đặt ngân sách và cảnh báo chi phí. `ruflo-testgen` tìm test còn thiếu và tạo test. Hai tên plugin này có trong bảng plugin của README. Phần tư liệu mình có không nêu chi tiết cách dùng từng plugin, nên hãy xem mô tả của chúng trong `/ruflo market`.

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

**Claude Code không thấy ruflo sau khi `init`.** Thường là do Claude Code đang mở từ trước. README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy tắt hẳn rồi mở lại trong đúng thư mục đã chạy `init`.

**Lệnh `/plugin` hoặc `claude plugin install` báo không nhận.** Có thể Claude Code của bạn cũ. Đường plugin cần bản 2.1.287 trở lên, cò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, rồi thử lại.

**`npx` báo lỗi phiên bản hoặc không chạy.** Repo yêu cầu Node 20 trở lên. Kiểm tra bằng `node --version`, nếu thấp hơn thì nâng cấp Node rồi chạy lại.

**Cài xong mà dự án đầy file lạ.** Đây là điều bình thường với `init`: nó thêm `.claude/`, `.claude-flow/`, `CLAUDE.md` và các file khác. Nếu bạn không muốn đụng vào dự án chính, hãy thử trên một thư mục thử nghiệm trước, hoặc chọn đường plugin vì README ghi là không thêm file nào vào dự án.

**Cài cùng một plugin từ hai marketplace.** README cảnh báo với các plugin bên ngoài như `agentdb` hay `agentic-qe-fleet`: chỉ nên cài từ một marketplace, nếu không mod và lệnh sẽ bị nạp hai lần. Nếu thấy lệnh bị trùng, hãy gỡ bớt một bản.

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

**Điểm mạnh.** Cài rất nhanh, một lệnh là xong. Giấy phép MIT, repo còn được cập nhật. Có hai đường cài (đầy đủ hoặc chỉ plugin) và chạy được với cả Claude Code lẫn Codex. Bảng điều khiển cho bạn nhìn thấy agent đang làm gì, tốn bao nhiêu token, và quyền hạn của Claude được đặt ở mức an toàn theo mặc định.

**Giới hạn.** Hệ thống rất lớn: hàng trăm công cụ, hàng chục plugin, nhiều khái niệm như swarm, federation, bộ nhớ vector. Với người mới, dễ bị choáng nếu cố tìm hiểu hết. README cũng tự nói rõ nhiều phần minh hoạ là dữ liệu mẫu hoặc mô hình khái niệm, không phải bằng chứng việc đã hoàn thành. Các mod không được sandbox, nên bạn cần cẩn trọng với những gì mình cài. Tư liệu mình có không nêu chi phí vận hành cụ thể: bạn vẫn trả cho mô hình AI bạn dùng.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code sửa vài file nhỏ, bản Claude Code thuần có thể đã đủ và đơn giản hơn. Nếu bạn muốn dùng đúng một tiện ích riêng lẻ, hãy cài từng plugin thay vì cả bộ. Còn nếu bạn làm việc thật với dự án lớn và muốn agent có bộ nhớ, phối hợp và có chỗ theo dõi, ruflo là ứng viên đáng thử, nhất là trên một dự án thử trước khi áp dụng 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 bạn được dùng, sửa và phân phối theo điều khoản MIT. Tư liệu không nói gì về phí của ruflo. Tuy vậy, các mô hình AI chạy phía sau (ví dụ qua Claude Code) vẫn tính phí theo tài khoản của bạn.

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

Cần Node.js từ 20.0.0 trở lên và một thư mục dự án để chạy `npx ruflo@latest init`. Muốn cài theo đường plugin thì cần Claude Code bản 2.1.287 trở lên. Tư liệu không nói rõ về GPU hay yêu cầu phần cứng khác.

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

Claude Code là mô hình kèm công cụ cơ bản. ruflo là lớp harness bao quanh, thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook, MCP server và bảng điều khiển. Nếu bạn chỉ làm việc nhỏ thì Claude Code thuần có thể đã đủ.

### ruflo có chạy với Codex không?

Có. README nói Codex và các client MCP khác dùng được: bạn cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Chi tiết cách khai báo trong từng client thì tư liệu chưa nêu.

### Cài ruflo có làm thay đổi dự án của tôi không?

Có nếu dùng `npx ruflo@latest init`: lệnh này thêm các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` vào dự án. Đường chỉ cài plugin thì README ghi là không thêm file nào vào dự án. Với `init grok`, README nói có thêm cờ `--dry-run` để xem trước.

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

README nói mặc định là read + ask, bạn tự chọn nâng quyền. Hành động vượt quyền sẽ bị từ chối, còn 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. Bạn có thể bấm Take back control để dừng.

### Dữ liệu của tôi có được gửi ra ngoài không?

Tư liệu chưa nói đầy đủ về luồng dữ liệu. README chỉ đề cập rằng phần học bằng truy xuất vector cục bộ có thể chạy mà không cần LLM, còn embedding và module học đã cấu hình vẫn cần thiết. Bạn nên tự xem tài liệu bảo mật của repo (SECURITY.md) trước khi dùng với dữ liệu nhạy cảm.
