# 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 bộ khung (harness) bọc quanh Claude Code và Codex. Nó thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên và máy chủ MCP vào dự án của bạn. Cài chỉ cần một lệnh npx trong thư mục dự án, nhưng cần Node 20 trở lên.

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

ruflo là một «agent meta-harness» cho Claude Code và Codex: một lớp công cụ bao quanh mô hình AI, giúp mô hình có thêm agent chuyên biệt, bộ nhớ, vòng lặp tự kiểm tra và các chốt kiểm soát. Trước đây dự án tên là Claude Flow, do Reuven Cohen (rUv) tạo ra. Hiện repo có khoảng 81.582 sao và 9.607 fork, giấy phép MIT, viết chủ yếu bằng TypeScript.

Tác giả giải thích bằng một công thức: Agent = Mô hình + Harness. Mô hình lo phần viết. Harness cấp công cụ, trí nhớ, vòng lặp và giới hạn để mô hình làm việc được thật. ruflo là phần harness đó. Một lệnh `init` là Claude Code có thêm đội agent biết chia việc, nhớ lại việc cũ giữa các phiên và (nếu bạn dùng liên kết) nói chuyện với agent trên máy khác.

Ai nên dùng? Lập trình viên, kể cả người mới, đang dùng Claude Code hoặc Codex và muốn giao việc dài hơn một câu lệnh đơn lẻ, chẳng hạn rà soát cả repo, viết test, tóm tắt thay đổi. Điểm đáng giá nhất: README nói rõ bạn không phải học hết hàng trăm công cụ. Sau `init`, bạn cứ dùng Claude Code như bình thường, hệ thống hook tự định tuyến và phối hợp agent ở nền.

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

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

Dưới đây là những phần bạn sẽ thấy hữu ích nhất khi mới bắt đầu.

### Đội agent và swarm

Kiểu cài qua CLI cho bạn 98 agent, hơn 60 lệnh và 30 skill. Các agent tự tổ chức thành swarm để chia việc. Lợi ích thực tế: bạn giao một mục tiêu lớn, ví dụ «rà soát repo này», rồi để nhiều agent cùng xử lý thay vì ngồi hỏi từng bước.

### Bộ nhớ qua nhiều phiên

ruflo có bộ nhớ để agent nhớ lại việc đã làm, cộng với các plugin truy xuất như ruflo-agentdb (cơ sở dữ liệu vector cho bộ nhớ agent), ruflo-rag-memory (tìm kiếm lai, đi theo đồ thị) và ruflo-rvf (lưu và khôi phục bộ nhớ giữa các phiên). README ghi rằng phần học bằng 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ấu hình.

### Hook tự định tuyến

Sau `init`, hook gắn vào Claude Code để định tuyến tác vụ, học từ mẫu thành công và điều phối agent ngầm. Bạn không phải gõ lệnh riêng cho từng việc.

### Bảng điều khiển trong Claude Code

Plugin `ruflo-console` là một «buồng lái» cạnh Claude Code. Nó cho bạn theo dõi workflow, agent, mô hình, token và chi phí. Bạn mở nó bằng lệnh `/ruflo`. Bạn cũng xem được log và kết quả của từng agent, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy.

### Cho Claude lái, bạn đặt giới hạn

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 tại là read + ask. Hành động vượt mức quyền bị từ chối. Hành động liên quan mạng, chi tiền và phá huỷ vẫn phải xác nhận ngay cả khi ở `auto`. Nút **Take back control** dừng ngay quyền điều khiển của Claude.

### Hệ plugin lớn

README liệt kê 48 plugin (cộng 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học tập, kiểm thử, bảo mật, kiến trúc, vận hành. Một vài ví dụ:

- ruflo-testgen tìm test còn thiếu và tạo test.
- ruflo-security-audit quét lỗ hổng và CVE.
- ruflo-cost-tracker theo dõi token, đặt ngân sách, báo động chi phí.
- ruflo-docs tự tạo và duy trì tài liệu.

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

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong package.json. Gói npm tên là `claude-flow` và có lệnh CLI, còn lệnh khuyên dùng trong README là `npx ruflo@latest init`.
- **Claude Code** (hoặc Codex / một MCP client khác). Nếu bạn muốn cài kiểu plugin trong Claude Code thì cần Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` từ terminal cần bản **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy `init`.
- Về hệ điều hành, GPU hay API key: README đoạn mình có không nêu yêu cầu cụ thể. Phần còn lại của README bị cắt nên mình không khẳng định thêm. Bạn xem file README.md và thư mục docs trong repo để biết chi tiết.

```note
Các mod của ruflo chạy với quyền tài khoản của bạn và không bị đưa vào sandbox. README khuyên đọc mã nguồn trước khi cài. Đừng cài mod mà bạn chưa xem qua.
```

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

Có ba đường chính. Mình khuyên người mới bắt đầu bằng đường 1, vì README mô tả đây là cách cho đầy đủ vòng chạy.

```steps
- Kiểm tra Node | Chắc chắn máy có Node 20 trở lên
- Mở terminal trong dự án | Vào đúng thư mục dự án của bạn
- Chạy init | Gõ npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nạp ruflo
- Giao thử một việc | Dán một câu lệnh mẫu vào Claude Code
```

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

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

```bash
node --version
```

### Vào thư mục dự án

Chỗ này người mới hay vấp: phải chạy lệnh **trong thư mục dự án** của bạn, vì `init` ghi file vào chính thư mục đó. Thay đường dẫn bằng đường dẫn thật của bạn.

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

### Chạy lệnh init

Đây là lệnh chính theo 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, kiểu cài này tạo thêm các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings trong thư mục của bạn. Nếu muốn cấu hình từng bước có hướng dẫn, README có lệnh:

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

### Mở lại Claude Code

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nạp các thành phần ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code, hãy thoát và mở lại.

### 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. Nó cài công cụ lõi, bảng điều khiển và các mod. Gõ 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
```

Với Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal:

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

Lưu ý từ README: kiểu plugin này nhẹ hơn. Nó thêm lệnh slash và định nghĩa agent. Máy chủ MCP chỉ có khi cài ruflo-core, và hook thì không được cài. Muốn dùng đủ vòng chạy thì chọn `init`.

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

Cấu hình **command** là `npx` và **arguments** là mảng sau:

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

Hoặc nếu client cho nhập một lệnh nguyên, đó là `npx -y ruflo@latest mcp start`.

### Cách khác: chạy giao diện terminal

Bảng điều khiển chạy được riêng, 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

Cách kiểm tra theo tư liệu:

1. Sau `init`, mở lại Claude Code trong thư mục dự án. Bạn nên thấy các file mới như `.claude/` và `CLAUDE.md` trong thư mục.
2. Gõ `/ruflo` trong Claude Code. Nếu bảng điều khiển hiện ra, phần console đã chạy.
3. Với cách cài plugin, gõ `/plugin` và xem plugin có nằm trong dòng mod đang hoạt động không.
4. Với MCP-only, kiểm tra client của bạn đã liệt kê máy chủ ruflo.
5. Với giao diện terminal, `npx ruflo tui` phải mở được màn hình bảng điều khiển.

README không đưa ra một đoạn log mẫu cho lệnh `init`, nên mình không dám mô tả chính xác chữ nó in ra. Nếu thấy lỗi, bạn xem phần dưới.

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

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

### Dev mới nhận một repo lạ cần rà soát

Bạn vừa nhận một dự án cũ và chưa biết chỗ nào dễ hỏng. Sau khi chạy `init` và mở lại Claude Code, bạn dán đú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: các agent tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn nên đọc kỹ phần test trước khi giữ lại, vì AI vẫn có thể viết test chưa đúng ý.

### Quản lý dự án muốn thấy agent đang làm gì

Bạn không biết code nhưng muốn nhìn tiến độ. Bạn cài ruflo-console, mở `/ruflo` và xem workflow, agent, token và chi phí cùng lúc. Khi có lỗi, bạn mở log từng agent, tìm kiếm và so sánh các lần chạy. Cái bạn nhận được là một chỗ để nhìn thấy AI làm gì, thay vì chỉ đọc đoạn chat dài.

### Thử cho Claude điều khiển bảng điều khiển, có giới hạn

Đây là bài thử mà README mô tả từng bước. Vào Settings → Claude control và chọn **write + ask**. Rồi bảo Claude:

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

Claude mở mục Missions và đặt mục tiêu. Bạn bấm 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. Lưu ý quan trọng từ README: tạo mission không có nghĩa là tính năng đã được làm xong.

> Agent = Model + Harness. Mô hình viết, còn harness giúp nó làm việc được thật.
>
> — Ông T

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

Bạn không dùng Claude Code mà dùng Codex. Bạn trỏ client tới máy chủ MCP của ruflo bằng command `npx` với các đối số ở trên. Kết quả là công cụ của ruflo xuất hiện trong client mà bạn không phải thêm file nào vào dự án.

```note
Đặt mức quyền thấp trước (read + ask) rồi mới nâng dần. Hành động tốn tiền hoặc phá huỷ vẫn cần bạn xác nhận, nhưng bạn nên tự kiểm tra log hành động thường xuyên và biết nút Take back control nằm đâu.
```

## 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 thường gặp là Node cũ hơn 20. Chạy `node --version`, cập nhật Node nếu cần rồi chạy lại `npx ruflo@latest init`.

### Không thấy ruflo trong Claude Code sau khi init

Claude Code chỉ nạp ruflo ở lần khởi động kế tiếp. Hãy thoát hẳn và mở lại, và nhớ mở đúng thư mục bạn vừa chạy `init`. Nếu dùng plugin, chạy `/reload-plugins` rồi `/plugin` để xem danh sách.

### Lệnh /plugin không nhận hoặc cài plugin thất bại

Kiểm tra phiên bản Claude Code. Cài plugin cần 2.1.287 trở lên, còn `claude plugin install` từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code nếu bản của bạn thấp hơn.

### Cài một plugin hai lần và bị lặp lệnh

README cảnh báo với plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow: chỉ cài từ **một** marketplace. Nếu bật từ cả hai, mod và lệnh sẽ tải hai lần. Hãy gỡ một bản.

### Claude từ chối thực hiện một hành động

Đây là hành vi đúng thiết kế. Nếu mức quyền thấp hơn hành động cần, hoặc bạn bấm Take back control, lệnh sẽ bị từ chối. Nâng mức quyền trong Settings → Claude control nếu bạn thật sự muốn, hoặc khôi phục quyền điều khiển.

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

**Điểm mạnh.** Chỉ một lệnh là có sẵn cả đội agent, hook, bộ nhớ và MCP. Có bảng điều khiển để theo dõi, có mức quyền rõ ràng, giấy phép MIT, và repo vẫn được cập nhật trong 3 tháng gần đây. Số sao lớn cho thấy cộng đồng quan tâm nhiều.

**Giới hạn.** Dự án rất rộng: hàng trăm công cụ MCP, hàng chục lệnh và 48 plugin. Người mới dễ choáng, nên hãy bắt đầu với `init` và một việc nhỏ. README cũng nói thẳng rằng các video demo dùng dữ liệu mẫu hoặc phát lại khung hình, nên chúng không chứng minh swarm đã hoàn thành việc thật. Bạn hãy tự thử trên dự án của mình. Ngoài ra, `init` ghi nhiều file vào thư mục dự án, nên hãy dùng trong repo có quản lý phiên bản để xem lại thay đổi.

**Khi 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 hoặc sửa một file nhỏ, ruflo là hơi thừa. Nếu bạn chỉ muốn thử vài lệnh, cài đúng một plugin sẽ nhẹ hơn. Nếu bạn lo về an toàn, hãy đọc mã mod trước khi cài vì chúng không chạy trong sandbox.

## 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 được mà không phải trả phí bản quyền. Tuy nhiên chi phí gọi mô hình AI (qua Claude Code, Codex...) thì không nằm trong tư liệu mình có. Plugin ruflo-cost-tracker giúp theo dõi token và đặt ngân sách.

### Cần Node.js phiên bản nào?

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

### ruflo chạy được với Codex không, hay chỉ Claude Code?

Chạy được với cả hai. README nói Codex và các MCP client khác dùng được bằng cách trỏ tới lệnh npx với đối số -y, ruflo@latest, mcp, start.

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

Có với cách npx ruflo@latest init. README nói nó thêm các mục như .claude/, .claude-flow/, CLAUDE.md và file settings vào thư mục. Nếu muốn không thêm file nào, bạn có thể chọn cách chỉ cài plugin trong Claude Code, nhưng khi đó chỉ có phần lệnh slash và agent.

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

README nói mức mặc định của Claude control là read + ask. Hành động vượt mức quyền bị từ chối, còn hành động liên quan mạng, chi tiền và phá huỷ phải xác nhận kể cả ở chế độ auto. Riêng các mod chạy với quyền tài khoản của bạn và không bị sandbox, nên cần đọc mã trước khi cài.

### Có cần GPU hay API key riêng không?

Tư liệu mình có không nêu yêu cầu GPU hay API key cụ thể cho cách cài cơ bản. Một số plugin như ruflo-ruvector nhắc đến tìm kiếm tăng tốc GPU, nhưng đó là phần tuỳ chọn. Bạn xem README.md và thư mục docs trong repo để biết thêm.

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

Claude Code trần là mô hình kèm công cụ cơ bản. ruflo là lớp harness thêm đội agent, swarm, bộ nhớ qua nhiều phiên, hook tự định tuyến và bảng điều khiển. Theo README, sau init bạn vẫn dùng Claude Code bình thường và các phần này chạy ở nền.
