# 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 mã nguồn mở: nó thêm agent, hook, bộ nhớ và MCP server vào dự án để Claude Code hay Codex làm việc theo nhóm. Bạn dùng nó để giao việc lớn cho nhiều agent phối hợp, có nhớ giữa các phiên. 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-10-04 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-ai-claude-code-codex-huong-dan-4

Ruflo là một “agent harness”: lớp công cụ đặt quanh Claude Code hoặc Codex để mô hình AI không chỉ trả lời, mà còn làm việc theo nhóm, có bộ nhớ và có kiểm soát. README viết gọn: mô hình lo phần viết, harness lo phần công cụ, bộ nhớ, vòng lặp và giới hạn. Repo này trước đây tên Claude Flow, nay đổi tên thành Ruflo, hiện có khoảng 81.500 sao và 9.600 fork, giấy phép MIT.

Vấn đề nó giải quyết khá đời thường. Bạn giao cho Claude Code một việc lớn, nó làm xong rồi quên sạch ở phiên sau. Việc nào cũng một agent ôm hết. Ruflo thêm vào dự án các agent chuyên biệt, cơ chế “swarm” (nhiều agent phối hợp như một đội), bộ nhớ giữ lại giữa các phiên và hook tự định tuyến công việc. Ai đang dùng Claude Code hoặc Codex hằng ngày và muốn giao việc nhiều bước hơn thì nên thử. Lập trình viên mới cũng dùng được, vì README nhấn mạnh sau khi `init` bạn cứ dùng Claude Code như bình thường.

Điểm đáng giá nhất: cài chỉ một lệnh, không cần học hết hàng trăm công cụ bên trong. README nói rõ bạn không cần học 406 công cụ MCP hay 61 lệnh CLI. Ngoài ra còn có “bảng điều khiển” (console) để xem agent, token và chi phí ngay cạnh Claude Code.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là lớp điều phối (harness) bọc quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ dài hạn và hook, cài bằng một lệnh npx.
- 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, theo đúng những gì README mô tả.

**Agent và swarm.** Đường cài bằng CLI cho bạn 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: bạn có thể nhờ một “swarm” chia việc, ví dụ một agent tìm module rủi ro, một agent viết test, một agent tóm tắt.

**Hook định tuyến tự động.** Sau `init`, hệ thống hook tự chọn cách xử lý tác vụ, học từ các mẫu làm thành công và điều phối agent chạy nền. Bạn không phải gọi từng agent bằng tay.

**Bộ nhớ qua nhiều phiên.** Ruflo có bộ nhớ vector để agent nhớ kinh nghiệm cũ. Các plugin liên quan gồm `ruflo-agentdb` (cơ sở dữ liệu vector cho bộ nhớ agent), `ruflo-rag-memory` (tìm kiếm thông minh) và `ruflo-rvf` (lưu và khôi phục bộ nhớ giữa các phiên). README ghi chú phần học này là “mô hình khái niệm”: 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.

**Bảng điều khiển trong Claude Code.** Plugin `ruflo-console` cho bạn xem workflow, agent, model, token và chi phí. Bạn mở bằng lệnh `/ruflo`. Có thể xem log từng lần chạy, tìm kiếm, phân loại lỗi, phát lại và so sánh.

**Cho Claude điều khiển bảng điều khiển, nhưng có 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 hành động mạng, tiêu tiền hoặc phá huỷ vẫn phải xác nhận kể cả khi để `auto`. Có nút “Take back control” để thu hồi quyền ngay.

**Kho plugin lớn.** README liệt kê 48 plugin, chia nhóm: điều phối, bộ nhớ, học máy, kiểm thử và chất lượng mã, bảo mật, kiến trúc, DevOps. Vài ví dụ dễ hiểu: `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 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ể trao đổi với nhau một cách an toàn. Phần này dành cho người dùng nâng cao, người mới có thể bỏ qua.

**Hỗ trợ nhiều client.** Ngoài Claude Code, Ruflo chạy với Codex và các client MCP khác. README còn có tuỳ chọn `--grok` cho Grok Build.

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

Tư liệu nói khá ít về yêu cầu, nên mình chỉ ghi những gì chắc chắn:

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json` của gói npm. Lệnh `npx` đi kèm Node.
- **Claude Code** (hoặc Codex, hoặc một client MCP khác) để dùng các agent sau khi cài.
- **Claude Code phiên bản 2.1.287 trở lên** nếu bạn chọn cách cài bằng plugin. Lệnh `claude plugin install` từ terminal cần bản 2.1.292 trở lên.
- Một terminal mở ngay trong thư mục dự án của bạn.

Về hệ điều hành, API key hay phần cứng (GPU): README phần mình có không nêu yêu cầu cụ thể. Phần cuối README bị cắt nên mình không khẳng định thêm. Nếu cần chắc chắn, bạn xem `README.md` và thư mục `docs/` trong repo.

```note
Dùng Ruflo với Claude Code hay Codex nghĩa là các agent vẫn gọi mô hình AI qua tài khoản của bạn, nên có thể phát sinh chi phí token. Mod của Ruflo chạy với quyền của tài khoản bạn và không bị sandbox, vì vậy hãy đọc mã trước khi cài. Plugin ruflo-cost-tracker có thể giúp theo dõi chi phí.
```

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

README có hai đường cài chính. Đường 1 (khuyên dùng cho dùng thật) là chạy `npx ruflo@latest init`. Đường 2 là cài plugin trong Claude Code, nhẹ hơn và không thêm file vào dự án.

```steps
- Mở terminal | Vào thư mục dự án 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 | Khởi động Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc | Dán câu lệnh mẫu để Claude dùng swarm
- (Tuỳ chọn) Mở bảng điều khiển | Gõ /ruflo trong Claude Code
```

### Mở terminal đúng thư mục

Lệnh `init` ghi file vào dự án, nên bạn phải đứng đúng thư mục dự án. Trên Windows, bạn có thể mở PowerShell rồi dùng `cd`. Ví dụ:

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

Thay phần sau `cd` bằng đường dẫn thật. Chỗ này người mới hay vấp: nếu chạy lệnh ở thư mục khác, Ruflo sẽ cài vào nhầm chỗ.

### 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. Theo README, `init` thêm agent, hook, bộ nhớ và MCP server vào dự án. Bảng so sánh trong README nói đường này tạo ra các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file helper và settings. Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README ghi thêm:

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

### Mở Claude Code và giao việc thật

Sau `init`, hãy khởi động lại Claude Code trong cùng thư mục, vì README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Rồi dán 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: cài bằng plugin trong Claude Code

Cách này không thêm file vào dự án, chỉ cài công cụ lõi, bảng điều khiển và các mod. Gõ từng dòng sau 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
```

Dòng đầu thêm “chợ” plugin của Ruflo. Ba dòng `install` cài từng plugin. `/reload-plugins` nạp lại, còn `/ruflo` mở bảng điều khiển. Từ terminal, với Claude Code 2.1.292 trở lên, README ghi lệnh:

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

Lưu ý từ README: đường plugin chỉ cho một phần chức năng (lệnh slash, vài skill, định nghĩa agent), không có hook. Muốn đủ bộ như tài liệu mô tả thì dùng đường `init`.

### Dùng với Codex hoặc client MCP khác

Không cần thiết lập dự án. Bạn cấu hình client với command là `npx` và arguments là:

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

Nghĩa là client sẽ tự chạy `npx -y ruflo@latest mcp start` để bật MCP server của Ruflo. Chỗ điền cấu hình này tuỳ từng client; Ruflo README không chỉ chi tiết, bạn xem tài liệu của client bạn dùng.

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

Có vài dấu hiệu theo README:

- Sau `init`, thư mục dự án có thêm `.claude/`, `.claude-flow/` và file `CLAUDE.md`.
- Mở lại Claude Code, gõ `/ruflo` thì bảng điều khiển hiện ra.
- Nếu cài bằng plugin, mở `/plugin` và kiểm tra các plugin xuất hiện ở dòng “active mods”.
- Muốn thử bảng điều khiển ngoài Claude Code, chạy:

```bash
npx ruflo tui
```

Thêm `--plain` để in ra đúng một khung hình, tiện cho script. README cũng khuyên một bài thử gọn: vào Settings, mục Claude control, chọn write + ask, rồi bảo Claude tạo một “mission” và kiểm tra nó xuất hiện trong trang Missions, đồng thời Overview ghi lại hành động. Lưu ý chính README nhắc: tạo mission không có nghĩa tính năng đã được viết xong.

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

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

Bạn là lập trình viên nhận lại một repo cũ, chưa biết chỗ nào dễ hỏng. Sau khi `init` và mở lại Claude Code, bạn dán đúng 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.
```

Kết quả mong đợi: một nhóm 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 trước, rồi mới xem từng thay đổi.

> Mô hình chỉ viết. Phần còn lại, bộ nhớ, công cụ và giới hạn, mới là thứ khiến nó làm được việc.
>
> — Ông T

### Theo dõi việc agent đang làm qua bảng điều khiển

Bạn không muốn agent chạy mà không biết nó đang làm gì. Cài bảng điều khiển bằng plugin, mở `/ruflo`, vào Settings, chọn Claude control mức write + ask. Rồi nhờ Claude:

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

Claude mở trang Missions và đặt mục tiêu; bạn xác nhận hành động tạo khi hệ thống hỏi. Kết quả: mission xuất hiện trong Missions và Overview ghi lại thao tác. Bạn có thể bấm “Take back control” bất cứ lúc nào để tạm dừng các công cụ điều khiển của Claude.

### Dùng Ruflo từ Codex hoặc công cụ MCP khác

Nhân viên kỹ thuật đã quen Codex và không muốn đổi công cụ. Trong cấu hình MCP của client, đặt command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`. Khi client khởi động, nó nối được vào MCP server của Ruflo, nên các công cụ bộ nhớ và điều phối có thể gọi từ đó. Mức độ công cụ nào hiển thị còn tuỳ client.

### Thử trước khi cam kết, bằng plugin riêng lẻ

Bạn là người mới, chưa muốn thêm file lạ vào dự án. Hãy chọn đường plugin và chỉ cài thứ mình cần, ví dụ:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo
```

Bạn có lệnh slash và định nghĩa agent mà không có file nào trong dự án. Nếu thấy hữu ích mới chuyển sang `npx ruflo@latest init`. Nếu quan tâm chi phí, README liệt kê thêm plugin `ruflo-cost-tracker` để theo dõi token và đặt ngân sách.

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

**Lệnh npx báo lỗi phiên bản Node.** Gói yêu cầu Node từ 20.0.0. Kiểm tra bằng `node --version`, nếu thấp hơn thì nâng Node lên 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ũ. README yêu cầu 2.1.287 trở lên cho plugin, và 2.1.292 trở lên cho lệnh `claude plugin install` ở terminal. Cập nhật Claude Code rồi thử lại.

**Gõ `/ruflo` mà không thấy gì.** Thử `/reload-plugins`, hoặc đóng và mở lại Claude Code trong đúng thư mục đã chạy `init`. Mở `/plugin` xem plugin đã nằm trong danh sách active chưa.

**Claude từ chối thao tác trong bảng điều khiển.** Đây có thể không phải lỗi. Mặc định Claude control ở mức read + ask, và các hành động vượt mức quyền sẽ bị từ chối. Nếu bạn muốn nó tạo mission, vào Settings nâng lên write, nhưng hãy giữ chế độ ask để tự duyệt.

**Plugin bị nạp hai lần.** Với một số plugin ngoài như `agentdb`, `agentic-flow` và `agentic-qe-fleet`, README dặn chỉ cài từ một marketplace; cài từ cả hai thì mod và lệnh bị nạp đôi. Hãy chọn một nơi duy nhất.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Giấy phép MIT. Repo vẫn được cập nhật trong vài tháng gần đây. Phạm vi rộng: agent, swarm, bộ nhớ, bảng điều khiển, hàng chục plugin. Có lớp kiểm soát quyền rõ ràng (mức read/write/manage/full, ask/auto) và nút thu hồi quyền.

**Giới hạn.** Hệ thống rất lớn, nên người mới dễ thấy rối; bạn nên bắt đầu từ một việc nhỏ. README tự nói phần “học” là mô hình khái niệm, và các đoạn demo dùng dữ liệu mẫu, không phải bằng chứng cho việc swarm hoàn thành việc thật. Mod chạy với quyền tài khoản của bạn và không bị sandbox. Ngoài ra, các agent vẫn gọi mô hình AI nên chi phí vẫn do bạn chịu.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code làm việc đơn lẻ, nhỏ, không cần bộ nhớ hay nhiều agent, thì Claude Code trần là đủ và đỡ phức tạp. Nếu chỉ cần một khả năng cụ thể như kiểm thử hay bộ nhớ, hãy thử cài đúng một plugin thay vì cả bộ. Còn nếu bạn muốn giao việc nhiều bước, có nhớ và có theo dõi, Ruflo đáng để thử trong một dự án nhỏ trước.

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

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

Mã nguồn dùng giấy phép MIT nên dùng miễn phí. Tuy nhiên các agent vẫn gọi mô hình AI qua Claude Code, Codex hoặc nhà cung cấp bạn cấu hình, nên chi phí token do tài khoản đó tính. Tư liệu chưa nêu bảng giá cụ thể.

### Ruflo khác gì Claude Flow?

Cùng một dự án. README nói Claude Flow nay đã đổi tên thành Ruflo, do cùng tác giả đặt. Gói npm của repo hiện vẫn mang tên claude-flow trong khai báo, còn lệnh khuyến nghị cài là npx ruflo@latest init.

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

Bạn cần Node.js từ phiên bản 20.0.0 trở lên theo package.json, và Claude Code (hoặc Codex, hay client MCP khác). Nếu cài bằng plugin thì cần Claude Code từ 2.1.287 trở lên. Về GPU hay API key riêng, tư liệu mình có chưa nói rõ.

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

Tư liệu hiện có không nêu danh sách hệ điều hành được hỗ trợ. Lệnh cài chỉ cần Node và npx, nên về nguyên tắc bạn có thể thử, nhưng hãy xem README và thư mục docs trong repo để chắc chắn.

### Cài Ruflo có thêm file vào dự án của mình không?

Có nếu bạn dùng npx ruflo@latest init: nó tạo .claude/, .claude-flow/, CLAUDE.md và một số file helper, settings. Nếu cài bằng plugin trong Claude Code thì README ghi là không thêm file nào vào workspace.

### Claude có tự ý làm việc nguy hiểm trong bảng điều khiển không?

Mặc định quyền ở mức read kèm ask. Hành động vượt mức quyền bị từ chối, và 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 kể cả ở chế độ auto. Bạn có thể bấm Take back control để dừng quyền điều khiển của Claude.

### Dùng với Codex được không?

Được theo README. Bạn trỏ Codex hoặc client MCP khác vào lệnh npx với tham số -y, ruflo@latest, mcp, start. Cách điền cấu hình cụ thể tuỳ từng client nên bạn xem tài liệu của client đó.
