# Ruflo: điều phối nhóm 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 giúp Claude Code và Codex làm việc theo nhóm: có agent chuyên biệt, bộ nhớ qua nhiều phiên, hook tự động và MCP server. Bạn chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án, rồi mở lại Claude Code. Cài không khó nếu máy đã có Node 20 trở lên, nhưng bộ công cụ khá lớn nên nên bắt đầu từ một việc nhỏ.

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

Ruflo là một «harness» (bộ khung điều khiển) bọc quanh Claude Code và Codex. Nói đơn giản: mô hình AI lo viết, còn Ruflo lo phần còn lại, gồm công cụ, bộ nhớ, vòng lặp kiểm tra và các giới hạn an toàn để AI làm việc có tổ chức hơn. Repo hiện có khoảng 81582 sao và 9607 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.

Vấn đề Ruflo giải quyết là thế này. Dùng Claude Code một mình, mỗi phiên làm việc gần như bắt đầu lại từ đầu và chỉ có một «người» làm tất cả. Ruflo thêm vào dự án của bạn nhiều agent chuyên biệt có thể phối hợp thành «swarm» (đàn agent), cộng bộ nhớ để lần sau còn nhớ việc lần trước. Nó phù hợp với lập trình viên đã dùng Claude Code hoặc Codex và muốn giao việc lớn hơn, như rà soát cả repo, viết test hay theo dõi chi phí.

Điểm đáng giá nhất là cách bắt đầu rất gọn: một lệnh `init`, sau đó bạn cứ dùng Claude Code như bình thường. README nói bạn không cần học hết hàng trăm công cụ MCP hay các lệnh CLI. Hook sẽ tự định tuyến việc và phối hợp 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ớ, hook và MCP server chỉ với một lệnh init.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Ruflo là một bộ công cụ lớn. Dưới đây là những phần hữu ích nhất cho người mới, diễn giải theo README.

- **Agent chuyên biệt và swarm.** README nói bản cài bằng CLI thêm 98 agent, hơn 60 lệnh và 30 skill. Bạn có thể nhờ Claude dùng «một swarm» để chia việc, ví dụ một agent tìm chỗ rủi ro, một agent viết test.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ kinh nghiệm từ các việc trước và đưa lại vào lần định tuyến sau. README lưu ý đây là sơ đồ khái niệm. Phần 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ấu hình.
- **MCP server.** Claude Code, Codex hoặc client MCP khác có thể gọi các công cụ của Ruflo qua một lệnh duy nhất.
- **Hook tự động.** Sau `init`, hook sẽ giúp Claude Code định tuyến tác vụ và học từ các mẫu thành công mà bạn không phải làm tay.
- **Bảng điều khiển (console) ngay cạnh Claude Code.** Bạn theo dõi workflow, agent, model, token và chi phí. Bạn cũng xem được log, tìm kiếm, phát lại và so sánh các lần chạy. Mở bằng lệnh `/ruflo`.
- **Cho Claude điều khiển console, nhưng bạn đặt giới hạn.** Trong Settings → Claude control, bạn chọn mức `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 hay xoá luôn cần bạn xác nhận, kể cả ở chế độ `auto`.
- **Hơn 40 plugin riêng lẻ.** Bạn có thể chỉ lấy một phần, ví dụ `ruflo-testgen` (tìm test còn thiếu và tạo test), `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí), `ruflo-security-audit` (quét lỗ hổng) hay `ruflo-docs` (tạo và duy trì tài liệu).
- **Federation.** Agent trên các máy khác nhau có thể trao đổi với nhau một cách an toàn. Đây là tính năng nâng cao, người mới chưa cần.

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

Tư liệu chỉ nêu những điều sau:

- **Node.js 20.0.0 trở lên.** Đây là yêu cầu trong package.json. Lệnh `npx` đi kèm Node nên bạn không cần cài thêm gì.
- **Claude Code** (hoặc Codex, hoặc client MCP khác). Với cách cài bằng plugin, README yêu cầu Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` từ terminal cầ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 đó.

README không nói rõ về hệ điều hành, GPU hay API key riêng cho Ruflo. Phần này chưa có thông tin trong tư liệu. Bạn vẫn cần tài khoản để dùng Claude Code hoặc Codex như bình thường.

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

README mô tả hai đường cài khác nhau. Đường đầy đủ là `npx ruflo init`, cho bạn toàn bộ vòng làm việc. Đường nhẹ là plugin trong Claude Code, không thêm file nào vào dự án. Bài này đi theo đường đầy đủ trước, vì README ghi đó là cách phù hợp cho việc dùng thật.

```steps
- Kiểm tra Node | Chắc chắn máy có Node 20 trở lên
- Mở terminal đúng chỗ | Vào thư mục dự án của bạn
- Chạy init | Một lệnh npx để 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
- Giao việc thử | Dán một yêu cầu thật để xem swarm làm việc
```

### Kiểm tra Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS) và gõ lệnh dưới đây. Kết quả phải là phiên bản 20 trở lên. Nếu thấp hơn, bạn cần cập nhật Node trước.

```bash
node --version
```

### Mở terminal đúng chỗ

Chỗ người mới hay vấp nhất: lệnh `init` ghi file vào thư mục hiện tại. Vì vậy hãy `cd` vào dự án bạn muốn dùng, đừng chạy ở thư mục chung như Desktop hay ổ C. Tên thư mục dưới đây chỉ là ví dụ.

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

### Chạy init

Đây là lệnh chính theo README. Theo README, lệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Cách cài này tạo các thư mục `.claude/`, `.claude-flow/`, file `CLAUDE.md` cùng các file hỗ trợ và cài đặt, nên bạn sẽ thấy dự án có thêm file mới.

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

Nếu muốn thiết lập từng bước theo kiểu hỏi đáp, README có lệnh riêng:

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

### Mở lại Claude Code

Claude Code đọc cấu hình mới ở lần khởi động kế tiếp. Vì vậy nếu đang mở sẵn, hãy thoát rồi mở lại trong cùng thư mục dự án.

### Giao việc thử

Dán yêu cầu mẫu sau vào Claude Code. Đây là prompt đúng 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á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õ các lệnh sau ngay trong Claude Code. Cách này cài công cụ lõi, console và các mod, và cần Claude Code 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 cũng có lệnh:

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

```note
Các mod chạy với quyền của tài khoản bạn và không bị đóng khung (sandbox). README khuyên đọc mã của mod trước khi cài. Hãy làm theo lời khuyên này, nhất là trên máy có dữ liệu công việc quan trọng.
```

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

Với Codex hay client MCP, bạn không cần cài theo kiểu dự án. Chỉ cần cấu hình MCP với **command** là `npx` và **arguments** như sau:

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

Bạn cũng có thể chạy bảng điều khiển ngay trong terminal, không cần Claude Code:

```bash
npx ruflo tui
```

Thêm `--plain` nếu muốn in một khung hình duy nhất cho script.

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

Theo tư liệu, có vài dấu hiệu để bạn tự kiểm tra:

- Sau `npx ruflo@latest init`, trong thư mục dự án xuất hiện các thư mục `.claude/`, `.claude-flow/` và file `CLAUDE.md`.
- Mở lại Claude Code rồi gõ `/ruflo`. Nếu console hiện ra, phần cài đặt đã hoạt động.
- Với đường cài plugin, gõ `/plugin` và xem các mod có xuất hiện trong dòng «active mods» hay không.
- Cách thử thực tế nhất là chạy prompt mẫu ở trên và xem Claude có điều phối nhiều agent để rà soát repo hay không.

README chưa mô tả một dòng kết quả cố định cho lệnh `init`, nên mình không đưa ra đoạn output mẫu. Nếu muốn xem chi tiết, hãy đọc README.md và thư mục `docs/` trong repo.

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

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

Bạn vừa nhận một dự án cũ và không biết đụng vào đâu trước. Sau khi `init` và mở lại Claude Code, bạn dán đúng prompt mẫu của README: nhờ một swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã thay đổi. Kết quả bạn nhận được là danh sách module cần chú ý, các file test mới và một bản tóm tắt thay đổi. Bạn nên đọc kỹ phần test trước khi đưa vào nhánh chính.

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

### Người chưa quen dòng lệnh muốn thử console

Bạn muốn thấy Ruflo làm gì mà không bị rối. Hãy cài plugin `ruflo-console`, mở `/ruflo`, vào Settings → Claude control và chọn **write + ask**. Sau đó yêu cầu Claude: «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, còn bạn xác nhận hành động tạo. Cuối cùng bạn kiểm tra mục Missions và Overview. README nhắc rõ: tạo mission không có nghĩa là tính năng đã được viết xong. Nếu muốn dừng, bạn bấm **Take back control**.

### Chủ dự án cần kiểm soát chi phí token

Khi cho nhiều agent chạy cùng lúc, chi phí dễ vượt tầm. Console của Ruflo hiển thị token và chi phí ngay cạnh Claude Code. Ngoài ra có plugin `ruflo-cost-tracker`, theo mô tả của README là theo dõi lượng token, đặt ngân sách và cảnh báo chi phí. Bạn cài như plugin thường:

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

Kết quả là bạn thấy mức tiêu hao trong lúc làm việc, thay vì chỉ biết khi nhận hoá đơn. Chi tiết cách đặt ngân sách chưa có trong phần README mình đọc được, nên hãy xem trang của plugin.

### Dev dùng Codex hoặc client MCP khác

Bạn không dùng Claude Code mà dùng Codex. Bạn chỉ cần khai báo MCP server với lệnh `npx` và các tham số `-y`, `ruflo@latest`, `mcp`, `start` như phần cài đặt. Client của bạn sẽ gọi được công cụ Ruflo, nhưng không có phần plugin và slash command riêng của Claude Code.

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

**Chạy `npx` báo lỗi hoặc không chạy được.** Nguyên nhân thường là Node cũ. package.json yêu cầu Node 20 trở lên. Hãy chạy `node --version`, nếu thấp hơn thì cập nhật Node rồi chạy lại.

**Lệnh `/plugin` hoặc `claude plugin install` không nhận.** Có thể Claude Code của bạn quá cũ. Cách plugin cần bản 2.1.287 trở lên, còn lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code rồi thử lại.

**Đã `init` nhưng Claude Code không thấy agent hay hook.** README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn và mở lại trong đúng thư mục dự án. Với plugin, thử `/reload-plugins`.

**Claude từ chối thao tác trong console.** Đây thường là do thiết kế an toàn. Mặc định là read + ask, và các hành động vượt mức quyền bạn đặt sẽ bị từ chối. Mạng, chi tiêu và thao tác phá huỷ luôn cần xác nhận. Nếu cần, hãy nâng quyền trong Settings → Claude control, nhưng chỉ khi bạn hiểu mình đang cho phép gì.

**Cài cùng một plugin từ hai marketplace.** README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb và agentic-flow: nên cài từ một marketplace duy nhất, 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. Dùng được với Claude Code, Codex và các client MCP. Có sẵn bảng điều khiển để thấy agent đang làm gì, và có cơ chế phân quyền rõ ràng khi cho AI thao tác. Giấy phép MIT, dự án vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Bộ công cụ rất lớn, người mới dễ choáng. README tự lưu ý một số demo dùng dữ liệu mẫu, không phải bằng chứng cho việc swarm hoàn thành công việc hay nhớ lại được bộ nhớ. Phần bộ nhớ và học tập vẫn cần embedding và module cấu hình. Đường `init` còn thêm khá nhiều file vào dự án, bạn nên thử trên một nhánh hoặc dự án nhỏ trước. Các mod chạy không sandbox, vậy nên cần thận trọng với quyền truy cập.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code trả lời vài câu hỏi hay sửa vài file nhỏ, Claude Code thuần là đủ và gọn hơn. Nếu bạn không viết code hoặc chưa dùng Claude Code, Codex, hãy làm quen công cụ đó trước rồi hẵng thêm Ruflo.

## 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ó thể dùng mã nguồn tự do. Tuy nhiên bạn vẫn cần tài khoản và chi phí riêng cho Claude Code hoặc Codex. Tư liệu chưa nói về gói trả phí của Ruflo.

### Cần cài những gì trước khi chạy Ruflo?

package.json yêu cầu Node 20.0.0 trở lên. Bạn cần có Claude Code, Codex hoặc một client MCP. Nếu cài bằng plugin trong Claude Code, README yêu cầu bản 2.1.287 trở lên.

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

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

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

Có. README nói Codex và các client MCP khác dùng được. Bạn cấu hình lệnh `npx` với tham số `-y`, `ruflo@latest`, `mcp`, `start`.

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

Phần mình đọc được của README không nêu yêu cầu GPU hay hệ điều hành cụ thể. Yêu cầu duy nhất được ghi rõ là Node 20 trở lên. Bạn nên xem README.md và thư mục docs/ trong repo để chắc chắn.

### Cho Claude điều khiển Ruflo có an toàn không?

Ruflo cho bạn đặt mức quyền read, write, manage hoặc full, và chế độ 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á huỷ vẫn cần xác nhận ngay cả ở 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 có sandbox.

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

README mô tả Ruflo là lớp harness bọc quanh Claude Code, thêm agent chuyên biệt, swarm, bộ nhớ, hook và MCP server. Claude Code thuần không có sẵn các phần này. Tư liệu chưa có so sánh chi tiết về hiệu năng giữa hai cách.
