# 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 (tiền thân là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex để nhiều AI agent phối hợp, nhớ việc qua các phiên và tự học từ kết quả. Cài bằng một lệnh npx trong thư mục dự án, cần Node 20 trở lên. Người mới có thể dùng Claude Code như bình thường sau khi init, các phần phối hợp chạy ngầm.

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

ruflo là một **agent meta-harness** cho Claude Code và Codex. Hiểu đơn giản: Claude hay Codex là "bộ não" viết code, còn ruflo là bộ đồ nghề đặt quanh bộ não đó, gồm công cụ, bộ nhớ, vòng lặp kiểm tra và các giới hạn an toàn. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, viết chủ yếu bằng TypeScript, giấy phép MIT.

Vấn đề nó giải quyết: khi bạn giao một việc lớn cho một AI agent duy nhất, nó dễ quên ngữ cảnh, làm tuần tự và không rút kinh nghiệm cho lần sau. ruflo thêm hơn 100 agent chuyên biệt, cho chúng làm việc theo nhóm (swarm), lưu bộ nhớ giữa các phiên và có thể kết nối agent trên nhiều máy khác nhau.

Repo hiện có khoảng 81.600 sao và khoảng 9.600 fork, vẫn được cập nhật trong 3 tháng gần đây. Điểm đáng giá nhất với người mới: README nói rõ bạn không cần học hết hàng trăm công cụ. Sau `init`, bạn cứ dùng Claude Code như thường, phần định tuyến và phối hợp agent chạy nền.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, 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ế.

- **Agent chuyên biệt và swarm.** Thay vì một AI làm hết, nhiều agent chia việc và phối hợp như một nhóm nhỏ. Bạn giao một mục tiêu, nhóm tự chia.
- **Bộ nhớ xuyên phiên.** Agent nhớ những gì đã làm ở các phiên trước. Bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code.
- **Hook và tự học.** Hệ thống hook tự định tuyến tác vụ và ghi nhận mẫu làm việc thành công để dùng lại. README mô tả đây là vòng học mang tính khái niệm, và phần tìm kiếm vector cục bộ chạy được mà không cần LLM, nhưng vẫn cần embedding và các module học đã cấu hình.
- **MCP server.** Claude Code, Codex hoặc bất kỳ ứng dụng khách MCP nào cũng gọi được công cụ của ruflo.
- **Bảng điều khiển (console).** Một "buồng lái" đặt cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí; xem log, tìm kiếm, phân loại lỗi và so sánh các lần chạy.
- **Cho Claude điều khiển có 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 là read + ask. Hành động liên quan mạng, chi tiêu hoặc 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 (cộng 3 plugin bên ngoài): swarm, tạo test, kiểm tra bảo mật, theo dõi chi phí token, bộ nhớ RAG, tài liệu tự động và nhiều thứ khác. Bạn chọn cái cần dùng.
- **Federation.** Agent trên các máy khác nhau có thể trao đổi an toàn mà không làm lộ dữ liệu, theo mô tả của tác giả.

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

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

- **Node.js phiên bản 20.0.0 trở lên** (package.json yêu cầu như vậy), vì cách cài chính dùng `npx`.
- **Claude Code** nếu muốn dùng theo cách phổ biến nhất. Riêng đường cài bằng plugin thì cần Claude Code **2.1.287 trở lên**. Lệnh cài plugin từ terminal cần bản **2.1.292 trở lên**.
- Hoặc **Codex / ứng dụng khách MCP khác** nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy `init` (lệnh này thêm file vào dự án).

README phần đầu không nói cần GPU, cũng không nói rõ hệ điều hành hỗ trợ. Một số tính năng dùng LLM sẽ cần tài khoản và key của nhà cung cấp mà bạn cấu hình; tư liệu đoạn đầu chưa nêu chi tiết, bạn xem thêm trong README và thư mục `docs/` 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 bị sandbox. Hãy đọc mã nguồn trước khi cài. Khi mới thử, giữ chế độ Claude control ở mức mặc định read + ask.
```

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

```steps
- Kiểm tra Node | Chắc chắn máy có Node 20 trở lên
- Mở terminal ở thư mục dự án | Đứng đúng thư mục bạn muốn thêm ruflo
- Chạy init | npx ruflo@latest init
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nạp agent, hook, bộ nhớ
- Giao một việc thật | Dán câu lệnh mẫu và xem kết quả
```

### Kiểm tra Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và gõ:

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 20, bạn cần cập nhật Node trước. Đây là chỗ người mới hay vấp nhất.

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

Lệnh `init` thêm file vào thư mục hiện tại, nên bạn phải đứng đúng thư mục dự án. Ví dụ với một dự án có sẵn:

```bash
cd ten-thu-muc-du-an
```

`ten-thu-muc-du-an` là tên thư mục của bạn. Nếu chưa có dự án, tạo một thư mục trống để thử cho an toàn.

### Chạy init

Đây là lệnh cài chính, chép đúng theo README:

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

Lệnh này thêm agent, hook, bộ nhớ và MCP server của ruflo vào dự án. Theo bảng so sánh trong README, cách cài này tạo ra các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng các file hỗ trợ và settings. Bạn sẽ thấy file mới xuất hiện trong dự án, đó là bình thường.

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

Claude Code nạp cấu hình ở lần khởi động kế tiếp. Vì vậy hãy mở (hoặc khởi động lại) Claude Code **trong cùng thư mục** vừa chạy init. Mở sai thư mục thì nó không thấy ruflo.

### Các cách cài khác

**Chỉ cài plugin Claude Code (không thêm file vào dự án).** Chạy các lệnh sau bên trong Claude Code:

```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 lệnh:

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

Cách này nhẹ hơn: README nói plugin cho lệnh gạch chéo, vài skill và định nghĩa agent, không cài hook. Cách `npx ruflo@latest init` mới có đủ vòng chạy (README ghi 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon). Nếu muốn dùng thật, README khuyên chọn cách init.

**Codex hoặc ứng dụng khách MCP khác.** Cấu hình lệnh (command) là `npx` và đối số (arguments) là:

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

Nói cách khác, ứng dụng khách sẽ chạy `npx -y ruflo@latest mcp start`. Chỗ điền các giá trị này nằm trong phần cấu hình MCP của từng ứng dụng, README chưa chỉ chi tiết cho từng ứng dụng.

**Chạy bảng điều khiển trong terminal thường, 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

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

1. Sau `npx ruflo@latest init`, thư mục dự án có thêm các mục như `.claude/`, `.claude-flow/` và `CLAUDE.md`.
2. Mở lại Claude Code trong thư mục đó rồi gõ `/ruflo`. README nói đây là cách mở bảng điều khiển.
3. Nếu cài bằng plugin, gõ `/plugin` và xem các mod có xuất hiện trong dòng "active mods" không.
4. Thử nhanh bảng điều khiển ở terminal bằng `npx ruflo tui`.

README phần đầu không ghi một dòng "thành công" cố định để đối chiếu. Cách chắc nhất là giao một việc thật (xem phần sau) và xem Claude Code có điều phối agent không.

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

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

Bạn vừa nhận một dự án chưa quen và cần biết chỗ nào rủi ro nhất. Sau khi init và mở lại Claude Code, 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.
```

Kết quả mong đợi: một nhóm agent đọc repo, chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn nên đọc kỹ phần thay đổi trước khi giữ lại.

> Agent = Model + Harness. Model viết, còn harness mới giúp nó làm việc thật.
>
> — Ông T

### Người làm kinh doanh muốn theo dõi chi phí và tiến độ

Bạn dùng Claude Code cho nhiều việc và lo tốn token. Cài plugin bảng điều khiển bằng các lệnh `/plugin` ở trên rồi gõ `/ruflo`. README mô tả bảng điều khiển theo dõi workflow, agent, model, token và chi phí cạnh Claude Code. Plugin `ruflo-cost-tracker` trong danh sách còn ghi là theo dõi token, đặt ngân sách và cảnh báo chi phí. Kết quả: bạn nhìn được mỗi việc tốn bao nhiêu mà không phải đoán.

### Tạo "nhiệm vụ" bằng chính Claude, có kiểm soát

Đây là kịch bản README mô tả từng bước, phù hợp để làm quen với việc cho Claude điều khiển bảng điều khiển:

1. Cài console như trên, mở `/ruflo`, vào Settings → Claude control và chọn **write + ask**.
2. Yêu cầu Claude tạo một mission, ví dụ thêm nút bật tắt chế độ tối, và cho xem mission cùng trạng thái.
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 có ghi lại hành động.

Lưu ý README nhấn mạnh: tạo mission không có nghĩa tính năng đã được làm. Nếu muốn dừng, bấm **Take back control** để tạm khoá công cụ điều khiển của Claude.

### Dùng ruflo với Codex hoặc công cụ MCP khác

Nếu bạn dùng Codex hay một ứng dụng hỗ trợ MCP, không cần init vào dự án. Cấu hình MCP với lệnh `npx` và đối số như phần cài đặt, rồi gọi công cụ của ruflo từ ứng dụng đó. Kết quả là bạn có bộ nhớ và công cụ điều phối mà không thêm file nào 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 được.** Thường do Node quá cũ hoặc chưa cài. Kiểm tra bằng `node --version`; cần từ 20 trở lên theo package.json.

**Claude Code không thấy agent, hook của ruflo.** Rất hay do mở Claude Code ở thư mục khác, hoặc chưa mở lại sau `init`. Thoát hẳn, mở lại ngay trong thư mục đã chạy init. Nếu dùng plugin, thử `/reload-plugins`.

**Lệnh `/plugin install` không nhận hoặc báo thiếu.** README ghi plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 cho lệnh cài từ terminal). Hãy cập nhật Claude Code trước.

**Gọi nhầm tên công cụ MCP khi dùng plugin.** README ghi rõ: `ruflo-core` đăng ký MCP riêng, công cụ có tên dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, không phải `memory_store` trần như khi cài bằng CLI. Nếu làm theo tài liệu viết cho cách cài kia mà thấy sai tên, đây là lý do.

**Cài hai lần một plugin ngoài từ hai marketplace.** README cảnh báo một số plugin ngoài (như `agentic-qe-fleet`, `agentdb`, `agentic-flow`) chỉ nên cài từ một marketplace, nếu bật từ hai nơi thì mod và lệnh bị nạp hai lần. Chọn một nguồn và gỡ nguồn còn lại.

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

**Điểm mạnh:**

- Một lệnh `npx` là có agent, hook, bộ nhớ và MCP server, rất gọn cho người đã dùng Claude Code.
- Có bảng điều khiển để nhìn thấy agent đang làm gì, chi phí bao nhiêu.
- Có nhiều lớp kiểm soát: mức quyền, chế độ duyệt, nút lấy lại quyền điều khiển.
- Giấy phép MIT, dự án vẫn được cập nhật, có cả đường cài chỉ bằng plugin để thử nhẹ.

**Giới hạn:**

- Hệ thống rất lớn (README nhắc hàng trăm công cụ MCP, hàng chục lệnh), người mới dễ choáng. Cứ dùng Claude Code như bình thường và bỏ qua phần chưa cần.
- `init` thêm nhiều file vào dự án. Nếu bạn muốn dự án sạch, dùng đường plugin hoặc thử trong một thư mục riêng.
- Chính README nói phần "tự học" là mô hình khái niệm, và các bả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 công việc thật. Hãy tự kiểm tra kết quả.
- Mod chạy với quyền tài khoản bạn và không sandbox, nên cần đọc mã trước khi cài.

**Khi nào 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à thừa. Nó đáng dùng khi việc đủ lớn để chia cho nhiều agent, cần bộ nhớ lâu dài hoặc cần theo dõi chi phí.

## 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 khi agent gọi mô hình AI, chi phí gọi mô hình (ví dụ qua Claude Code) tính theo tài khoản của bạn. Tư liệu chưa nêu bảng giá cụ thể.

### ruflo có cần GPU không?

Phần README mình đọc không yêu cầu GPU để cài và chạy. Một plugin trong danh sách (ruflo-ruvector) có nhắc tìm kiếm tăng tốc bằng GPU, nhưng đó là tuỳ chọn và tư liệu chưa nói cần thiết.

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

package.json yêu cầu Node từ 20.0.0 trở lên. Lệnh cài chính là npx ruflo@latest init, chạy trong thư mục dự án của bạn.

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

Phần README được cung cấp chưa nói rõ về hệ điều hành hỗ trợ. Cách cài dùng npx và Node nên về nguyên tắc chạy trong terminal có Node, nhưng chưa có thông tin chính thức, bạn nên xem README và thư mục docs của repo.

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

ruflo là lớp bọc quanh Claude Code và Codex. Nó thêm hơn 100 agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook tự định tuyến, bảng điều khiển và guardrail bảo mật. Bạn vẫn dùng Claude Code như bình thường, các phần phối hợp chạy ngầm.

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

Có, nếu dùng npx ruflo@latest init: lệnh này thêm các mục như .claude/, .claude-flow/, CLAUDE.md và file hỗ trợ vào dự án. Nếu muốn không thêm file nào, README có cách cài chỉ bằng plugin Claude Code, nhưng cách đó có ít tính năng hơn.

### Cho Claude điều khiển bảng điều khiển có an toàn không?

README nói mặc định là mức read kèm ask (hỏi trước). Hành động vượt quyền bị từ chối, và các hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần xác nhận dù để auto. Bạn có thể bấm Take back control để dừng ngay.
