# 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 để nhiều agent phối hợp thành đội, có bộ nhớ qua nhiều phiên làm việc. Bạn dùng nó để giao việc lớn cho Claude Code mà không phải tự điều phối từng bước. Cài khá đơn giản, chỉ cần Node 20 trở lên và chạy một lệnh npx trong thư mục dự án.

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

ruflo là một "agent meta-harness": một lớp công cụ đặt quanh Claude Code và Codex để biến một trợ lý AI đơn lẻ thành một đội agent biết phối hợp, nhớ việc cũ và tự rút kinh nghiệm. Nói gọn theo cách README đặt: 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, giới hạn an toàn. Repo này trước đây có tên Claude Flow, và hiện có khoảng 81.600 sao cùng 9.600 fork trên GitHub.

Nếu bạn đã dùng Claude Code và thấy mỗi lần giao việc lớn thì phải tự chia nhỏ, tự nhắc lại bối cảnh, thì ruflo nhắm đúng chỗ đó. Sau khi chạy `init`, bạn vẫn dùng Claude Code như bình thường. Phần định tuyến tác vụ, học từ các lần làm tốt và phối hợp agent chạy ngầm bằng hook.

Đ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 là đủ để thêm agent, hook, bộ nhớ và MCP server. Bạn không phải học hết hàng trăm công cụ. README nói thẳng là không cần học 406 công cụ MCP hay 61 lệnh CLI. Bài này đi từng bước để bạn cài được và thử được một việc thật.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ lâu dài, 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à các nhóm tính năng chính, giải thích theo lợi ích thực tế.

**Đội agent chuyên biệt (swarm).** ruflo đi kèm 100+ agent chuyên biệt (README ở phần so sánh cách cài ghi 98 agent), và có thể điều phối chúng làm việc theo nhóm. Bạn có thể ra một yêu cầu như "review repo này, tìm module rủi ro nhất, viết test, rồi tóm tắt", và các agent chia nhau làm thay vì một agent làm tuần tự.

**Bộ nhớ qua nhiều phiên.** Agent không quên mọi thứ khi bạn đóng cửa sổ. ruflo có bộ nhớ vector (README nhắc đến HNSW, AgentDB, RAG) để lưu và truy xuất lại kinh nghiệm. Lợi ích: lần sau bạn làm việc tương tự, agent đã có sẵn bối cảnh.

**Tự học từ việc đã làm.** README mô tả vòng học: bộ nhớ đưa kinh nghiệm hữu ích quay lại phần định tuyến. README cũng lưu ý đây là sơ đồ khái niệm. Việc 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.

**Hook tự động.** Sau `init`, hệ thống hook tự định tuyến tác vụ và phối hợp agent ở nền. Bạn không phải gõ lệnh riêng cho từng việc.

**Bảng điều khiển (console) ngay cạnh Claude Code.** Đây là "buồng lái" để theo dõi workflow, agent, mô hình, token và chi phí. Bạn có thể mở log từng agent, tìm kiếm, xem lại lỗi, so sánh các lần chạy. Mở bằng lệnh `/ruflo` trong Claude Code, hoặc chạy riêng ngoài terminal bằng `npx ruflo tui`.

**Cho Claude điều khiển console, nhưng bạn đặt giới hạn.** Trong Settings có mục Claude control với bốn mức: `read`, `write`, `manage`, `full`, và hai kiểu duyệt: `ask` hoặc `auto`. Mặc định hiện tại là read + ask. Các hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần bạn xác nhận, kể cả ở chế độ `auto`. Có nút **Take back control** để lấy lại quyền ngay.

**Hệ plugin lớn.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài) chia theo nhóm: điều phối, bộ nhớ, học máy, chất lượng code và test, bảo mật, kiến trúc, DevOps, mở rộng. Ví dụ `ruflo-testgen` tìm test còn thiếu và sinh test, `ruflo-cost-tracker` theo dõi token và đặt ngân sách, `ruflo-security-audit` quét lỗ hổng và CVE, `ruflo-aidefence` chặn prompt injection và phát hiện thông tin cá nhân.

**Liên kết nhiều máy (federation).** Agent trên các máy khác nhau có thể giao tiếp an toàn, README nói là không làm lộ dữ liệu. Phần này dành cho người cần nâng cao, người mới có thể bỏ qua.

**Dùng được với nhiều công cụ.** Ngoài Claude Code, README nói Codex và các MCP client khác cũng dùng được, và có lệnh `npx ruflo init --grok` cho Grok Build.

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

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

- **Node.js từ phiên bản 20.0.0 trở lên.** `package.json` của repo yêu cầu như vậy, và các lệnh cài đều dùng `npx` đi kèm Node.
- **Claude Code** nếu bạn đi theo đường chính. Muốn cài theo kiểu plugin thì cần 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`. Lệnh này thêm file vào thư mục đó.
- Nếu dùng Codex hoặc MCP client khác: chỉ cần client của bạn cho phép khai báo một MCP server bằng lệnh và tham số.

README phần đầu không nói rõ về hệ điều hành, API key hay phần cứng cụ thể. Mình cũng không thấy yêu cầu GPU trong phần tư liệu mình có. Nếu bạn cần chắc chắn về Windows hoặc cấu hình key cho từng nhà cung cấp, hãy xem thư mục `docs/` và file `README.md` trong repo.

```note
Các mod của ruflo chạy với quyền của tài khoản bạn và không được đưa vào sandbox. README khuyên đọc mã nguồn trước khi cài. Với console, hãy giữ mức Claude control thấp nhất đủ dùng, vì hành động tốn tiền hoặc phá huỷ vẫn cần bạn xác nhận.
```

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

README đưa ra vài đường cài. Đường nên chọn cho người mới là lệnh `init` trong thư mục dự án. Đường plugin nhẹ hơn nhưng ít tính năng hơn.

```steps
- Kiểm tra Node | Chắc chắn máy có Node 20 trở lên
- Mở terminal đúng thư mục | Vào thư mục dự án bạn muốn dùng ruflo
- Chạy init | Một lệnh npx thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude Code | Khởi động Claude Code trong cùng thư mục để nó nhận cấu hình
- Giao một việc thật | Nhập một yêu cầu dùng swarm để thử
```

### Kiểm tra phiên bản Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) và chạy:

```bash
node --version
```

Kết quả phải là `v20.0.0` hoặc cao hơn. Nếu thấp hơn hoặc báo không tìm thấy lệnh, bạn cần cài hoặc nâng cấp Node trước. Đây là chỗ người mới hay vấp nhất.

### Mở terminal trong thư mục dự án

Bạn phải đứng trong thư mục dự án thật, vì `init` ghi file vào đúng nơi bạn đang đứng. Ví dụ:

```bash
cd duong-dan/toi/thu-muc-du-an
```

Hãy thay `duong-dan/toi/thu-muc-du-an` bằng đường dẫn thật trên máy bạn.

### 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. 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`, cùng file helper và settings. Nghĩa là dự án của bạn sẽ có thêm file, nên nếu dùng Git, hãy xem lại phần thay đổi trước khi commit.

Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README có một lệnh khác:

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

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

Mở Claude Code trong cùng 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. Rồi thử một việc thật, ví dụ câu 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.
```

### 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, nhưng chỉ cho lệnh gạch chéo, một vài skill và định nghĩa agent. Chạy bên trong Claude Code (cần 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, với Claude Code 2.1.292 trở lên, README ghi:

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

Bạn có thể cài thêm từng plugin lẻ khi cần, ví dụ:

```text
/plugin install ruflo-swarm@ruflo
/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** là:

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

Cách này tương đương chạy `npx -y ruflo@latest mcp start`.

### Cách khác: chạy console ngoài Claude Code

```bash
npx ruflo tui
```

Thêm `--plain` nếu bạn muốn in ra một khung hình duy nhất, tiện cho script.

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

Có vài dấu hiệu theo tư liệu:

- Sau `init` và khi mở lại Claude Code, dự án của bạn có các thư mục `.claude/` và `.claude-flow/` cùng file `CLAUDE.md`.
- Trong Claude Code, gõ `/ruflo` để mở console. Nếu mở được, phần cài console đã ổn.
- Với đường plugin, mở `/plugin` và xem các mod có xuất hiện ở dòng "active mods" không.
- Thử một việc nhỏ qua console: đặt Claude control ở mức `write + ask`, rồi bảo Claude tạo một "mission". Bạn xác nhận thao tác tạo, rồi kiểm tra mission xuất hiện ở trang Missions và hành động được ghi ở Overview.

Lưu ý README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Nó chỉ chứng minh Claude điều khiển được console.

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

Các tình huống dưới đây bám theo khả năng có trong README. Kết quả cụ thể phụ thuộc vào dự án và mô hình bạn dùng, nên hãy xem đây là gợi ý cách bắt đầu.

### Lập trình viên mới nhận một repo lạ

Bạn vừa được giao một dự án cũ, không ai giải thích. Sau khi `init` và mở lại Claude Code, gõ câu 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.
```

Kết quả mong đợi: các agent rà soát, chỉ ra module rủi ro nhất, viết test cho nó và báo lại thay đổi. Bạn đọc bản tóm tắt thay vì lần mò từng file.

> Bạn vẫn viết code như bình thường, ruflo lo phần điều phối ở phía sau.
>
> — Ông T

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

Bạn dùng AI nhiều và sợ hoá đơn phình ra. Cài thêm plugin theo dõi chi phí (từ README):

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

Plugin này theo dõi lượng token, cho đặt ngân sách và cảnh báo chi phí. Kết hợp với console (`/ruflo`) để nhìn token và chi phí ngay cạnh Claude Code.

### Người phụ trách chất lượng cần bổ sung test

Dự án có nhiều hàm chưa được test. Cài plugin sinh test:

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

Theo README, plugin này tìm test còn thiếu và tự sinh. Bạn đưa yêu cầu cho Claude Code như "tìm chỗ thiếu test trong thư mục này và bổ sung". Sau đó hãy chạy bộ test của dự án và đọc lại từng test trước khi giữ, vì test do AI sinh vẫn cần người xem.

### Người dùng Codex hoặc công cụ MCP khác

Bạn không dùng Claude Code mà dùng một client MCP khác. Khai báo command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]` như phần cài đặt ở trên. Client sẽ gọi được các công cụ của ruflo mà không cần thêm file vào dự án.

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

**Lệnh `npx` báo lỗi hoặc không chạy.** Nguyên nhân hay gặp là Node cũ hơn yêu cầu. Chạy `node --version`, nếu dưới 20 thì nâng cấp Node rồi chạy lại.

**Claude Code không thấy ruflo sau khi `init`.** 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 và mở lại Claude Code trong đúng thư mục bạn đã chạy `init`. Chạy `init` ở thư mục khác thì Claude Code ở thư mục này sẽ không thấy gì.

**Lệnh `/plugin` không nhận hoặc cài plugin thất bại.** Đường plugin cần Claude Code từ 2.1.287 trở lên, còn lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi thử lại, và chạy `/reload-plugins` sau khi cài.

**Plugin chạy hai lần hoặc lệnh bị trùng.** 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 marketplace. Cài từ cả hai thì mod và lệnh sẽ tải hai lần. Hãy gỡ một bên.

**Tên công cụ MCP khác với tài liệu.** Nếu bạn cài bằng plugin, các công cụ của `ruflo-core` có tên dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, không phải tên ngắn như `memory_store` của đường CLI. Khi làm theo hướng dẫn nào đó, hãy để ý bạn đang dùng đường cài nào. Muốn có đầy đủ tên theo kiểu CLI thì dùng `npx ruflo@latest init`.

**Console từ chối hành động của Claude.** Đây là thiết kế, không phải lỗi. Hành động vượt mức quyền bạn đặt sẽ bị từ chối. Mở Settings → Claude control và nâng mức lên khi bạn thực sự muốn, nhớ rằng thao tác dùng mạng, tốn tiền và phá huỷ vẫn cần xác nhận.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có sẵn rất nhiều agent và plugin. Có bộ nhớ qua các phiên, có console để nhìn được agent đang làm gì, và có cơ chế giới hạn quyền khá rõ ràng. Giấy phép MIT, và repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Hệ thống rất lớn: hàng chục plugin, hàng trăm công cụ. Người mới dễ choáng, nên hãy bắt đầu chỉ với `init` rồi dùng Claude Code như thường. Lệnh `init` thêm nhiều file vào dự án, nên cần xem lại trước khi commit. Phần "tự học" và "liên kết nhiều máy" là các tính năng nâng cao, README tự lưu ý nhiều phần là sơ đồ khái niệm hoặc chỉ minh hoạ bằng dữ liệu mẫu, không phải bằng chứng cho mọi kết quả. Mod chạy với quyền tài khoản của bạn và không có sandbox.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần một agent làm vài việc nhỏ, Claude Code thuần đã đủ, không cần thêm lớp điều phối. Nếu dự án chứa dữ liệu nhạy cảm, hãy đọc kỹ SECURITY.md và mã của mod trước khi bật. Nếu bạn chỉ muốn thử, đường plugin (không thêm file vào dự án) là cách ít rủi ro hơn để làm quen.

## 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 mã nguồn dùng tự do. Tuy nhiên ruflo chạy trên Claude Code, Codex hoặc các nhà cung cấp AI khác, và chi phí của những dịch vụ đó là việc riêng. README có plugin theo dõi token và đặt ngân sách để bạn kiểm soát.

### ruflo cần phiên bản Node nào?

package.json yêu cầu Node từ 20.0.0 trở lên. Bạn có thể kiểm tra bằng lệnh node --version trước khi chạy npx.

### Cài ruflo bằng cách nhanh nhất là gì?

Mở terminal trong thư mục dự án và chạy npx ruflo@latest init, rồi mở lại Claude Code trong cùng thư mục. Lệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. Nếu không muốn thêm file nào, bạn có thể cài theo đường plugin trong Claude Code.

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

Theo README, ruflo là lớp harness bọc quanh Claude Code và Codex, thêm các agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên, hook và guardrail bảo mật. Claude Code vẫn là nơi bạn làm việc, còn ruflo lo phần điều phối ở nền.

### Có dùng được với Codex hoặc công cụ không phải Claude Code không?

Có. README nói Codex và các MCP client khác dùng được, bằng cách khai báo command npx với arguments -y, ruflo@latest, mcp, start. README cũng có lệnh init --grok cho Grok Build.

### Cho Claude điều khiển console có nguy hiểm không?

Mặc định là mức read kèm ask, tức chỉ đọc và hỏi bạn trước. Hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận kể cả ở chế độ auto, và có nút Take back control để dừng ngay. Mod chạy với quyền tài khoản của bạn nên README khuyên đọc mã trước khi cài.

### ruflo có cần GPU hay chạy được trên Windows không?

Phần tư liệu hiện có chưa nói rõ yêu cầu GPU hay hệ điều hành cụ thể. Các lệnh cài đều dựa trên Node và npx. Bạn nên xem thêm README.md và thư mục docs trong repo để chắc chắn.
