# ruflo: điều phối nhiều AI 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 agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên làm việc, hook và máy chủ MCP. Bạn dùng nó để giao việc lớn cho một nhóm agent phối hợp thay vì một agent đơn lẻ. Cài khá dễ: chạy một lệnh npx trong thư mục dự án, cần Node từ 20 trở lên.

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

ruflo là một "agent harness" mã nguồn mở: lớp công cụ đặt quanh Claude Code và Codex để các AI agent có thêm công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát. Nói đơn giản, mô hình AI là người viết, còn ruflo là cái bàn làm việc đầy đủ đồ nghề để người đó làm việc cho ra việc. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.588 sao và 9.608 fork trên GitHub, giấy phép MIT.

Bạn nên xem ruflo nếu đang dùng Claude Code hoặc Codex và thấy một agent đơn lẻ làm chưa đủ: việc lớn cần chia nhỏ, cần nhớ lại những gì đã làm hôm trước, cần có người rà soát. Lập trình viên mới hay người làm kinh doanh có biết chút dòng lệnh đều thử được, vì cài đặt chỉ là một lệnh.

Điểm đáng giá nhất là tác giả nhấn mạnh bạn không cần học hết hàng trăm công cụ bên trong. Sau khi chạy `init`, bạn cứ dùng Claude Code như bình thường; hook của ruflo tự định tuyến tác vụ, học từ các lần làm thành công và điều phối agent ở phía sau.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) thêm agent, bộ nhớ, hook và máy chủ MCP cho Claude Code và Codex, để nhiều agent phối hợp làm việc. 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 nêu, kèm lợi ích thực tế.

- **Nhóm agent (swarm).** ruflo có sẵn nhiều agent chuyên biệt và cho chúng phối hợp như một đội. Lợi ích: bạn giao một việc như "rà soát repo, viết test, tóm tắt thay đổi" và để các agent chia nhau làm.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ lại kinh nghiệm cũ thay vì bắt đầu từ trắng mỗi lần mở Claude Code. README cho biết phần truy xuất vector cục bộ có thể chạy mà không cần LLM, nhưng vẫn cần embedding và các module học được cấu hình.
- **Hook tự động.** Sau `init`, hook tự định tuyến tác vụ và học từ mẫu làm việc thành công, bạn không phải gọi từng công cụ.
- **Máy chủ MCP.** Codex hoặc các ứng dụng khách MCP khác cũng dùng được ruflo, không chỉ Claude Code.
- **Bảng điều khiển (console).** Theo dõi workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code, mở bằng lệnh `/ruflo`. Bạn có thể xem log, tìm kiếm, phát lại và so sánh các lần chạy.
- **Claude điều khiển console, bạn đặt giới hạn.** Trong Settings có mục Claude control với các mức `read`, `write`, `manage`, `full` và chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiêu hay phá hủy luôn cần bạn xác nhận, kể cả ở chế độ `auto`.
- **Hệ plugin.** Có 48 plugin, chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps... Ví dụ `ruflo-swarm` để phối hợp agent, `ruflo-testgen` để tìm chỗ thiếu test và sinh 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 có thể trao đổi an toàn. Đây là tính năng nâng cao, người mới chưa cần đến.

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

Tư liệu nói rõ những điều sau:

- **Node.js từ phiên bản 20.0.0 trở lên** (theo `package.json`). Lệnh `npx` đi kèm Node.
- **Claude Code** (hoặc Codex / một ứng dụng khách MCP) nếu bạn muốn dùng ruflo qua chúng.
- Nếu cài theo hướng chỉ dùng plugin của Claude Code, 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`.

README phần đã cung cấp không nói gì về yêu cầu phần cứng, GPU hay hệ điều hành cụ thể, nên mình không khẳng định. Phần tài khoản và API key cho từng nhà cung cấp mô hình, bạn xem thêm trong tài liệu của repo.

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

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

README đưa ra ba đường chính. Cách đầu tiên (chạy `init`) là cách tác giả đề xuất và cho kết quả đầy đủ nhất. Mình hướng dẫn cách này trước.

```steps
- Kiểm tra Node | Chắc chắn máy có Node từ 20 trở lên
- Mở terminal đúng chỗ | 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 vào dự án
- Mở Claude Code | Mở lại trong cùng thư mục để nó nhận cấu hình mới
- Giao việc thử | Dán một câu lệnh mẫu để xem swarm chạy
```

### Kiểm tra Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS) và xem phiên bản Node. Lệnh `node --version` là lệnh phổ thông, in ra số phiên bản. Cần từ 20 trở lên.

```bash
node --version
```

Nếu máy chưa có Node hoặc cũ hơn 20, bạn cần cài hoặc nâng cấp Node trước.

### 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 hiện tại**. Nếu bạn mở terminal ở sai chỗ (ví dụ thư mục Desktop), file sẽ nằm sai chỗ. Hãy `cd` vào đúng thư mục dự án trước.

```bash
cd duong-dan-toi-thu-muc-du-an-cua-ban
```

### Chạy init

Đây là lệnh trong README:

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

`init` thêm agent, hook, bộ nhớ và máy chủ MCP của ruflo vào dự án. Theo bảng so sánh trong README, cách này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings. Tức là nó sửa dự án của bạn, nên nếu dự án đang dùng Git thì nên commit trạng thái hiện tại trước để dễ so sánh.

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

Claude Code nhận cấu hình mới ở lần khởi động kế tiếp. Hãy mở (hoặc khởi động lại) Claude Code **trong cùng thư mục** đã chạy `init`.

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

Cách này không thêm file nào vào dự án. Bạn cần Claude Code 2.1.287 trở lên. Gõ các lệnh sau **bên trong Claude Code** (không phải trong 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
```

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

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

Lưu ý: README cảnh báo cách plugin chỉ cho "phiên bản nhẹ" (lệnh gạch chéo và một số skill). Bản đầy đủ gồm hook và daemon thì dùng `npx ruflo@latest init`.

### Cách khác: Codex hoặc ứng dụng khách MCP

Trong phần cấu hình MCP của ứng dụng, đặt **command** là `npx` và **arguments** là:

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

Hoặc chạy lệnh tương đương `npx -y ruflo@latest mcp start`.

### Cách khác: chạy console trong terminal thường

Bảng điều khiển 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, tiện cho script.

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

Theo README, bạn kiểm tra như sau:

1. Sau `npx ruflo@latest init`, trong thư mục dự án phải xuất hiện các mục như `.claude/`, `.claude-flow/` và `CLAUDE.md`.
2. Mở lại Claude Code rồi gõ `/ruflo`. Nếu console hiện ra, bạn đã có bảng điều khiển.
3. Nếu cài bằng plugin, gõ `/plugin` và xem các mod có nằm trong dòng "active mods" không.
4. Với console độc lập, `npx ruflo tui` phải mở giao diện trong terminal.

Phép thử thực tế nhất là cho Claude Code một việc thật (xem phần dưới) và xem nó có dùng swarm hay không.

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

### Rà soát một dự án có sẵn

**Bối cảnh:** bạn là lập trình viên mới nhận lại một dự án cũ, không biết chỗ nào dễ hỏng. Sau khi chạy `init` và mở lại Claude Code, bạn dán câu lệnh mẫu của chính 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:** 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 đọc phần tóm tắt, rồi tự chạy test và xem lại thay đổi trước khi giữ.

> Agent = Model + Harness. Mô hình lo viết, còn harness lo cho nó làm việc cho ra việc.
>
> — Ông T

### Tạo "mission" và giữ quyền kiểm soát

**Bối cảnh:** bạn muốn thử bảng điều khiển nhưng chưa dám để Claude tự làm hết. README có sẵn kịch bản:

1. Cài console (`ruflo-console@ruflo`), mở `/ruflo`, vào **Settings → Claude control**, chọn **write + ask**.
2. 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 thao tác tạo.
4. Kiểm tra Missions có mục tiêu đó và Overview có ghi lại hành động.

Lưu ý README nói rõ: tạo mission không có nghĩa tính năng đã được làm. Muốn dừng, bấm **Take back control**; các lệnh gọi sau đó của Claude sẽ bị từ chối cho đến khi bạn trả quyền lại.

### Theo dõi chi phí khi để agent chạy lâu

**Bối cảnh:** bạn giao nhiều việc cho agent và lo tốn token. README liệt kê plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí). Cài theo cú pháp chung của README:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-cost-tracker@ruflo
```

Sau đó mở console bằng `/ruflo` để xem token và chi phí cạnh Claude Code. README đã cung cấp không nêu chi tiết từng lệnh con của plugin này, bạn xem thêm trong tài liệu của plugin.

### Sinh test cho phần code còn thiếu

**Bối cảnh:** nhóm nhỏ có code chạy được nhưng gần như chưa có test. Plugin `ruflo-testgen` được mô tả là "tìm test còn thiếu và tạo chúng tự động". Cài giống ví dụ trên (`/plugin install ruflo-testgen@ruflo`) rồi nhờ Claude Code tìm chỗ thiếu test trong module bạn chọn. Kết quả là các file test đề xuất; hãy tự chạy và đọc lại, đừng tin mù quáng.

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

**Gõ lệnh `/plugin ...` vào terminal thường nên báo lỗi.** Các lệnh bắt đầu bằng dấu gạch chéo phải gõ bên trong Claude Code. Chỉ lệnh `npx ...` và `claude plugin install ...` mới gõ ở terminal.

**Cài xong mà Claude Code không thấy gì.** `init` cần Claude Code khởi động lại. Hãy đóng và mở lại trong đúng thư mục dự án. Với plugin, chạy `/reload-plugins`.

**Lệnh plugin không chạy do Claude Code quá cũ.** Cách plugin cần Claude Code 2.1.287 trở lên, lệnh `claude plugin install` cần 2.1.292 trở lên. Hãy cập nhật Claude Code.

**Lỗi Node hoặc npx.** `package.json` yêu cầu Node từ 20. Nếu `node --version` thấp hơn, nâng cấp Node rồi chạy lại.

**Dự án bị thêm nhiều file lạ.** `init` tạo `.claude/`, `.claude-flow/`, `CLAUDE.md` và các file khác. Nếu bạn chưa muốn thế, hãy thử trên một bản sao dự án, hoặc dùng cách chỉ cài plugin (không thêm file vào dự án).

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

**Điểm mạnh:** cài chỉ một lệnh; mã nguồn mở giấy phép MIT; repo vẫn được cập nhật trong vài tháng gần đây; hệ plugin rộng; có cơ chế giới hạn quyền (read/write/manage/full, ask/auto) và nút lấy lại quyền điều khiển.

**Giới hạn:** hệ thống rất lớn (README nhắc tới hàng trăm công cụ MCP và hàng chục lệnh CLI), nên người mới dễ choáng. Một số phần là khái niệm; README tự nói sơ đồ kiến trúc "không phải vết thực thi thật", và các đoạn demo dùng dữ liệu mẫu, không chứng minh swarm đã hoàn thành việc thật. Mod chạy không sandbox với quyền tài khoản của bạn. Tư liệu cũng không nêu rõ chi phí token khi chạy nhiều agent, nên hãy theo dõi sát.

**Khi nào chọn cách khác:** nếu bạn chỉ cần một trợ lý viết code đơn giản, dùng Claude Code hoặc Codex trần là đủ. Nếu bạn muốn thử nhẹ, hãy cài từng plugin thay vì toàn bộ. Chỉ nên lên bản đầy đủ khi bạn thật sự cần agent phối hợp, bộ nhớ dài hạn và hook tự động.

## Câu hỏi thường gặp

### ruflo có miễn phí không?

Repo dùng giấy phép MIT, mã nguồn mở. Tuy nhiên bản thân ruflo chỉ là lớp điều phối; chi phí gọi mô hình AI (ví dụ qua Claude Code) tùy thuộc nhà cung cấp bạn dùng. README có plugin theo dõi token và ngân sách để bạn kiểm soát.

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

Cần Node.js từ phiên bản 20 trở lên và một ứng dụng như Claude Code hoặc Codex. Cách cài chỉ bằng plugin yêu cầu Claude Code từ 2.1.287 trở lên.

### 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 thiết lập có hướng dẫn, dùng `npx ruflo@latest init wizard`.

### Ruflo có 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 ứng dụng khách MCP khác dùng được: đặt command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`.

### Cài plugin và chạy init khác nhau thế nào?

Plugin không thêm file nào vào dự án, chỉ cho lệnh gạch chéo, một số skill và định nghĩa agent. `init` cho bộ đầy đủ gồm agent, lệnh, skill, máy chủ MCP, hook và daemon, đồng thời thêm các thư mục như `.claude/` và `.claude-flow/` vào dự án.

### Ruflo có an toàn không, Claude có tự làm bậy được không?

Trong console, bạn chọn mức quyền (read, write, manage, full) và chế độ duyệt (ask hoặc auto). Mặc định hiện là read + ask, và các thao tác liên quan mạng, chi tiêu hay phá hủy luôn cần xác nhận. Tuy vậy các mod chạy với quyền tài khoản của bạn và không sandbox, nên cần đọc mã trước khi cài.

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

Tư liệu đã cung cấp không nêu yêu cầu GPU hay danh sách hệ điều hành được hỗ trợ, nên chưa có thông tin chắc chắn. Lệnh cài chỉ dựa trên Node và npx; bạn nên thử trên dự án nhỏ trước.
