# 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à bộ khung điều phối agent AI, chạy quanh Claude Code, Codex và các client MCP khác. Nó thêm agent chuyên biệt, bộ nhớ qua các phiên, hooks và bảng điều khiển vào dự án của bạn. Cài khá dễ: 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-11 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-ai-claude-code-codex-huong-dan-11

Ruflo là một "harness" (bộ khung) bao quanh Claude Code và Codex. Hiểu đơ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 đủ dụng cụ quanh người đó. Nó thêm công cụ, bộ nhớ, vòng lặp kiểm tra và cơ chế phối hợp nhiều agent để AI làm được việc dài hơi, thay vì chỉ trả lời từng câu.

Repo này dành cho người đã dùng (hoặc định dùng) Claude Code và muốn giao những việc lớn hơn: rà soát cả dự án, viết test, theo dõi chi phí token. Lập trình viên mới cũng dùng được, vì README nói rõ bạn không cần học hết hàng trăm công cụ bên trong. Sau khi cài, bạn cứ dùng Claude Code như bình thường, phần điều phối chạy nền.

Đ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à xong. Repo hiện có khoảng 81588 sao và 9608 fork, giấy phép MIT, viết chủ yếu bằng TypeScript và vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung (harness) bao quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, swarm phối hợp và bảng điều khiển, cài bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Theo README, Ruflo gom nhiều thứ vào một chỗ. Dưới đây là những ý có giá trị thực tế nhất với người mới.

### Agent và swarm

Sau khi `init`, dự án của bạn có sẵn nhiều agent chuyên biệt (README nói khoảng 98 agent ở đường cài CLI, ở phần khác ghi 100+). Các agent có thể chia thành "swarm" để cùng làm một việc: người tìm module rủi ro, người viết test, người tổng hợp. Lợi ích: bạn giao một yêu cầu lớn, không phải tự chia nhỏ từng bước.

### Bộ nhớ qua các phiên

Ruflo có bộ nhớ để agent nhớ lại kinh nghiệm giữa các lần làm việc, kèm tìm kiếm vector (HNSW, RAG). Hữu ích khi dự án lớn và bạn không muốn giải thích lại bối cảnh mỗi lần mở Claude Code. README lưu ý phần "tự học" hiện là mô hình khái niệm, và cần cấu hình embedding.

### Hooks tự động định tuyến

Hooks tự chọn agent hợp cho tác vụ và học từ những lần làm thành công. Bạn không cần gọi từng công cụ thủ công.

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

Plugin `ruflo-console` cho bạn một "cockpit" cạnh Claude Code: 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, xem lại và so sánh.

### Cho Claude điều khiển bảng điều khiển, 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, tức Claude chỉ đọc và hỏi bạn trước. Hành động liên quan mạng, chi tiêu hay phá hủy luôn cần bạn xác nhận, kể cả khi để `auto`.

### Hệ plugin

README liệt kê 48 plugin: swarm, theo dõi chi phí (`ruflo-cost-tracker`), tạo test (`ruflo-testgen`), quét bảo mật (`ruflo-security-audit`), tài liệu (`ruflo-docs`), bộ nhớ (`ruflo-agentdb`, `ruflo-rag-memory`)… Bạn chọn cái cần, không bắt buộc lấy hết.

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

Ngoài Claude Code, Codex và các client MCP khác cũng kết nối được qua một lệnh khởi động MCP server.

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

Chỉ những gì tư liệu nói:

- **Node.js từ 20.0.0 trở lên** (theo `package.json`). Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn dùng đường cài bằng plugin: cần phiên bản **2.1.287 trở lên**. Lệnh `claude plugin install` ở terminal cần **2.1.292 trở lên**.
- Một dự án (thư mục) để chạy `init`. Nếu chưa có, tạo thư mục trống cũng được.
- Codex hoặc client MCP khác: tùy chọn, nếu bạn muốn dùng ngoài Claude Code.

Tư liệu không nói rõ yêu cầu hệ điều hành, phần cứng hay API key riêng cho Ruflo. Bạn vẫn cần tài khoản/quyền dùng Claude Code (hoặc Codex) như bình thường. Muốn chắc về hệ điều hành, xem `README.md` và thư mục `docs/` trong repo.

```note
Gói npm của dự án có tên khai báo là claude-flow (tên cũ), nhưng README hướng dẫn gọi bằng ruflo. Bạn cứ chép lệnh đúng như trong bài này.
```

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

Ruflo có ba đường cài. Đường chính là `npx ruflo@latest init`, cho trải nghiệm đầy đủ nhất. Hai đường còn lại nhẹ hơn.

```steps
- Kiểm tra Node | Đảm bảo Node từ 20 trở lên
- Mở terminal đúng chỗ | Vào thư mục dự án của bạn
- Chạy init | Thêm agent, hooks, bộ nhớ, MCP server vào dự án
- Mở lại Claude Code | Khởi động lại trong cùng thư mục để nhận cấu hình
- Giao việc thử | Dán một yêu cầu thật cho swarm
```

### Kiểm tra Node và mở terminal đúng thư mục

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) rồi đi tới thư mục dự án. Lệnh `node --version` là lệnh phổ thông để xem phiên bản; bạn cần thấy số từ 20 trở lên.

```bash
node --version
cd duong-dan-toi-thu-muc-du-an
```

Chỗ người mới hay vấp: chạy `init` ở sai thư mục. Ruflo ghi file vào thư mục hiện tại, nên hãy chắc bạn đang đứng đúng trong dự án.

### Chạy lệnh init (đường chính)

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

Lệnh này thêm agent, hooks, bộ nhớ và MCP server của Ruflo vào dự án. Theo README, nó tạo các thư mục như `.claude/`, `.claude-flow/` và file `CLAUDE.md`, cùng settings. Vì thế dự án của bạn sẽ có thêm file mới. Nếu dự án quan trọng, nên commit hoặc sao lưu trước.

Muốn cài 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

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

### Đường thay thế: chỉ cài plugin trong Claude Code

Đường này không thêm file nào vào dự án. Chạy 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, trên Claude Code 2.1.292 trở lên, README ghi cách cài một plugin:

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

So sánh nhanh theo README: plugin thì "nhẹ", chủ yếu là lệnh slash và định nghĩa agent, không có hooks. Cài bằng `init` mới có đủ vòng lặp (agent, lệnh, skill, MCP server, hooks, daemon) và README khuyên dùng cho việc nghiêm túc.

```note
Các "mod" chạy với quyền tài khoản của bạn và không bị cô lập (sandbox). README dặn hãy đọc mã trước khi cài.
```

### Đường thay thế: Codex hoặc client MCP khác

Trong phần cấu hình MCP của client, đặt command là `npx` và arguments là danh sách sau:

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

Tương đương dòng lệnh `npx -y ruflo@latest mcp start`. Nếu bạn dùng Claude Code, hãy dùng `init` ở trên thay vì cách này.

### Chạy bảng điều khiển ngoài Claude Code

Bảng điều khiển cũng chạy độc lập trong terminal:

```bash
npx ruflo tui
```

Thêm `--plain` để in một khung hình, hợp khi dùng trong script.

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

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

- Sau `init`, trong thư mục dự án xuất hiện `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Mở lại Claude Code rồi gõ `/ruflo`: bảng điều khiển hiện ra.
- Nếu cài bằng plugin, gõ `/plugin` để xem các mod có nằm trong dòng "active mods" không.
- Thử `npx ruflo tui` ngoài terminal: nếu màn hình bảng điều khiển hiện ra là Node và gói đang chạy ổn.

Tư liệu không nêu một câu lệnh "kiểm tra phiên bản" riêng, nên mình không bịa ra. Nếu muốn kiểm tra sâu hơn, xem thư mục `docs/` và hướng dẫn người dùng trong repo.

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

### Dev rà soát một dự án đang chạy

Bối cảnh: bạn vừa nhận một dự án cũ, không rõ chỗ nào dễ hỏng. Sau khi chạy `init` và mở lại Claude Code, dán đúng prompt 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: swarm 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ự xem lại diff trước khi giữ thay đổi.

> Bạn không cần học hết hàng trăm công cụ. Cài xong, cứ dùng Claude Code như thường, phần điều phối chạy nền.
>
> — Ông T

### Chủ shop làm website tự theo dõi chi phí AI

Bối cảnh: bạn thuê người làm hoặc tự làm web bán hàng bằng Claude Code, và lo tiền token tăng lên mà không biết. Cài `ruflo-console` bằng đường plugin, mở `/ruflo` để xem token và chi phí cạnh Claude Code. README cũng có plugin `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí. Bạn vẫn là người quyết định có tiếp tục hay không.

### Người mới thử cho Claude tạo "mission" an toàn

Bối cảnh: bạn muốn thử cho Claude điều khiển bảng điều khiển nhưng sợ mất kiểm soát. Làm theo các bước README gợi ý:

1. Cài console, mở `/ruflo`, vào Settings → Claude control rồi chọn **write + ask**.
2. Nói với Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status."
3. Xác nhận hành động tạo khi bảng điều khiển hỏi.
4. Kiểm tra mục Missions có mục tiêu mới, và Overview ghi lại hành động.

Kết quả: bạn có một "mission" trong danh sách. README nhấn mạnh tạo mission không có nghĩa tính năng đã được viết xong. Nếu muốn dừng, bấm **Take back control**.

### Nhóm nhỏ nối Codex hoặc client MCP khác

Bối cảnh: nhóm bạn dùng Codex thay vì Claude Code. Trong cấu hình MCP của Codex, khai báo command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Codex sẽ gọi được các công cụ MCP của Ruflo mà không cần setup dự án. Muốn thiết lập dự án có hướng dẫn thì chạy `npx ruflo@latest init wizard`.

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

### Claude Code không thấy agent hay lệnh mới

Nguyên nhân thường gặp: Claude Code đang mở từ trước khi chạy `init`, hoặc mở sai thư mục. Hãy thoát, mở lại trong đúng thư mục dự án. Với plugin, thử `/reload-plugins`.

### Lệnh plugin báo không nhận hoặc không có

README yêu cầu Claude Code từ 2.1.287 trở lên (và 2.1.292 cho lệnh `claude plugin install` ở terminal). Hãy cập nhật Claude Code trước rồi thử lại.

### Lỗi Node hoặc npx

Node cũ hơn 20 có thể gây lỗi khi chạy. Chạy `node --version`, nếu thấp hơn thì cài Node mới rồi mở terminal mới.

### Cài cùng một plugin từ hai nơi

README cảnh báo với plugin ngoài như `agentdb` hoặc `agentic-qe-fleet`: chỉ cài từ một marketplace. Cài từ cả hai thì mod và lệnh bị nạp hai lần. Nếu thấy lệnh bị lặp, hãy gỡ một bản.

### Muốn thử nhưng sợ làm rối dự án

`init` thêm khá nhiều file vào dự án. Hãy thử trên một thư mục sao chép hoặc nhánh riêng trước. Hoặc dùng đường plugin, vì README nói đường này không thêm file nào vào workspace.

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

**Điểm mạnh:** cài rất nhanh bằng một lệnh; có bảng điều khiển để nhìn thấy agent, token và chi phí; có cơ chế phân quyền cho việc Claude điều khiển (mặc định chỉ đọc và hỏi); giấy phép MIT; dự án còn được cập nhật. Hệ sinh thái plugin rộng, bạn chọn phần cần dùng.

**Giới hạn:** dự án rất lớn (hàng trăm công cụ MCP, hàng chục lệnh), nên người mới dễ choáng nếu muốn khai thác hết. Một số phần như "tự học" README tự ghi là mô hình khái niệm, và các video minh họa 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 thật. Đường `init` thêm nhiều file vào dự án. Các mod không bị cô lập và chạy với quyền của bạn.

**Khi nào chọn cách khác:** nếu bạn chỉ cần Claude Code trả lời và sửa vài file nhỏ, dùng Claude Code thuần là đủ và gọn hơn. Chỉ nên cài Ruflo khi bạn thực sự cần nhiều agent phối hợp, bộ nhớ lâu dài hoặc theo dõi chi phí. Nếu chỉ muốn thử, hãy bắt đầu bằng đường plugin và thêm dần.

## 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 bạn dùng tự do. Tuy nhiên Ruflo chạy quanh Claude Code hoặc Codex, nên chi phí dùng các dịch vụ đó vẫn theo tài khoản của bạn. Tư liệu không nêu bảng giá riêng cho Ruflo.

### Ruflo khác gì Claude Code thuần?

Claude Code là công cụ viết code; Ruflo là lớp bao quanh nó, thêm agent chuyên biệt, swarm, bộ nhớ, hooks và bảng điều khiển. Sau khi cài, bạn vẫn dùng Claude Code như bình thường, còn Ruflo điều phối ở phía sau.

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

Cần Node.js từ 20.0.0 trở lên. Nếu cài bằng plugin thì cần Claude Code bản 2.1.287 trở lên (2.1.292 cho lệnh claude plugin install ở terminal). Tư liệu chưa nêu yêu cầu về GPU hay phần cứng riêng.

### Ruflo có chạy trên Windows không?

Tư liệu chưa nói rõ về hệ điều hành được hỗ trợ. Các lệnh chính chỉ là npx, nên về nguyên tắc chạy được nơi có Node 20 trở lên, nhưng bạn nên xem README và thư mục docs trong repo để chắc chắn.

### Ruflo có làm tôi mất file của dự án không?

Lệnh init thêm file và thư mục như .claude/, .claude-flow/ và CLAUDE.md vào dự án. Nên sao lưu hoặc dùng nhánh riêng trước khi thử. Nếu không muốn thêm file, README nói đường cài plugin không để lại file nào trong workspace.

### Claude có thể tự làm bậy trong bảng điều khiển không?

README nói mặc định hiện là read + ask: Claude chỉ đọc và phải hỏi bạn. Các hành động liên quan mạng, chi tiêu hay phá hủy vẫn cần xác nhận kể cả khi để auto, và bạn có nút Take back control để lấy lại quyền.

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

Được. README hướng dẫn cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"] trong Codex hoặc client MCP khác, không cần setup dự án.
