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

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

ruflo là một "harness" cho AI lập trình: lớp công cụ đặt quanh Claude Code hoặc Codex để chúng có thêm agent chuyên biệt, bộ nhớ, hook và cách phối hợp nhiều agent cùng làm một việc. Tác giả gọi nó là "agent meta-harness". Theo cách tác giả giải thích, mô hình AI lo phần viết, còn harness cấp công cụ, bộ nhớ, vòng lặp và các giới hạn để mô hình làm việc được thật sự.

Repo này dành cho ai đã dùng Claude Code (hoặc Codex) và thấy một cuộc trò chuyện đơn lẻ chưa đủ cho việc lớn như rà soát cả repo, viết test, theo dõi chi phí. Lập trình viên mới và người làm văn phòng có thể dùng, miễn là chấp nhận mở terminal gõ một lệnh. Hiện repo có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

Điểm đáng giá nhất là bạn không phải học hết. README nói rõ: sau khi chạy `init`, bạn cứ dùng Claude Code như bình thường, phần hook sẽ tự định tuyến tác vụ và điều phối agent ở nền. Bài này đi từ cài đặt, kiểm tra, đến vài tình huống dùng thật, kèm những giới hạn bạn nên biết trước.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ điều phối (harness) thêm agent, bộ nhớ, hook và MCP server cho Claude Code và Codex, 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ình diễn giải theo lợi ích thay vì chép lại README.

- **Thêm đội agent vào Claude Code.** Chế độ cài đầy đủ đưa vào dự án 98 agent, hơn 60 lệnh và 30 skill (theo bảng so sánh trong README). Bạn không cần tự viết từng agent "người review", "người viết test".
- **Swarm: nhiều agent làm việc như một nhóm.** Bạn có thể yêu cầu Claude dùng một swarm để rà soát repo, tìm module rủi ro nhất, viết test và tóm tắt thay đổi. Việc chia nhỏ và phối hợp do ruflo lo.
- **Bộ nhớ qua các phiên.** README mô tả bộ nhớ tự học và nhớ giữa các lần làm việc, dùng tìm kiếm vector. Lợi ích thực tế: đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code. README có ghi chú rằng phần học này vẫn cần embedding và các module học được cấu hình.
- **MCP server.** ruflo chạy như một MCP server, nên Codex hoặc các ứng dụng hỗ trợ MCP khác cũng dùng được.
- **Bảng điều khiển (console) trong Claude Code.** Bạn theo dõi workflow, agent, model, token và chi phí ngay cạnh Claude Code, mở bằng lệnh `/ruflo`. Có thể xem log từng lần chạy, tìm kiếm, xem lỗi, phát lại và so sánh.
- **Kho plugin lớn.** README liệt kê 48 plugin, chia nhóm: điều phối, bộ nhớ, học và suy luận, kiểm thử, bảo mật, DevOps, mở rộng. Ví dụ `ruflo-testgen` tìm test còn thiếu và sinh test, `ruflo-cost-tracker` theo dõi token và cảnh báo ngân sách, `ruflo-security-audit` quét lỗ hổng.
- **Giới hạn quyền cho Claude khi điều khiển console.** Bạn chọn mức `read`, `write`, `manage` hoặc `full`, kèm chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các thao tác mạng, tốn tiền hay phá huỷ vẫn phải xác nhận kể cả khi đang `auto`.
- **Liên kết giữa nhiều máy (federation).** Agent trên các máy khác nhau có thể trao đổi với nhau. Đây là phần nâng cao, người mới chưa cần.

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

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

- **Node.js từ phiên bản 20.0.0 trở lên.** `package.json` ghi yêu cầu này. Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn dùng cách cài vào dự án hoặc cách plugin. Riêng cách plugin cần Claude Code **2.1.287 trở lên**. Lệnh cài plugin từ terminal (`claude plugin install ...`) cần **2.1.292 trở lên**.
- **Một dự án (thư mục) để cài vào.** Lệnh `init` chạy trong thư mục dự án của bạn.
- **Codex hoặc ứng dụng MCP khác** nếu bạn không dùng Claude Code. Khi đó bạn chỉ cần trỏ nó tới ruflo.

Tư liệu không nói rõ về hệ điều hành, yêu cầu phần cứng hay API key riêng cho ruflo. Bạn dùng tài khoản và key của chính Claude Code hoặc Codex như bình thường. Mục "Chưa rõ" trong phần hỏi đáp cũng nhắc lại điều này.

```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ị cô lập (sandbox). README khuyên đọc code trước khi cài. Hãy thử trên một dự án nháp trước, đừng thử ngay trên repo quan trọng.
```

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

Có ba đường: cài đầy đủ vào dự án (khuyên dùng), cài chỉ plugin, hoặc chỉ cắm MCP. Mình hướng dẫn đường đầu tiên và nêu hai đường còn lại.

```steps
- Mở terminal đúng thư mục | 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ớ và MCP server
- Mở lại Claude Code | Mở trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc thật | Dùng câu lệnh mẫu của README
- Mở console | Gõ /ruflo để xem bảng điều khiển
```

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

Bạn cần đứng trong thư mục dự án, vì `init` ghi file vào đó (README nói sẽ có `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và settings). Chưa có dự án thì tạo thư mục thử trước. Trên Windows bạn có thể mở PowerShell rồi dùng `cd`.

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

Đổi `duong-dan-toi-du-an-cua-ban` thành đường dẫn thật. Lỗi hay gặp ở bước này là chạy lệnh ở sai thư mục, nên file bị ghi vào chỗ không mong muốn.

### 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 mà không cần cài toàn cục. `@latest` lấy bản mới nhất. Lệnh sẽ thêm agent, hook, bộ nhớ và MCP server vào dự án. Lần đầu có thể mất một lúc vì phải tải gói.

Nếu muốn thiết lập có hỏi đáp từng bước, README ghi:

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

Nếu muốn xem trước, README có nhắc cờ `--dry-run` cho bản Grok (`npx ruflo init --grok`), nhưng không nói cờ này có dùng được cho lệnh `init` thường hay không. Bạn nên xem tài liệu trong repo trước khi thử.

### Mở lại Claude Code

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

### Giao thử một việc

Dán câu mẫu trong README vào Claude Code:

```text
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.
```

Bạn có thể viết bằng tiếng Việt, nhưng README chỉ ghi câu tiếng Anh này làm ví dụ.

### 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. Gõ từng dòng 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
```

Từ terminal thường, với Claude Code 2.1.292 trở lên, README ghi:

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

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

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

Trỏ ứng dụng của bạn tới lệnh sau, cùng các tham số:

```text
npx -y ruflo@latest mcp start
```

Nếu ứng dụng đòi tách **command** và **arguments**, README ghi command là `npx` và arguments là:

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

Mỗi ứng dụng có chỗ khai báo MCP server khác nhau. README không hướng dẫn chi tiết cho từng ứng dụng, nên bạn xem tài liệu của ứng dụng đó.

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

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

1. Sau `init`, thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md`.
2. Mở lại Claude Code rồi gõ `/ruflo`. Bảng điều khiển hiện ra là cài thành công.
3. Với cách plugin, gõ `/plugin` và kiểm tra các mod xuất hiện trong dòng active mods.
4. Muốn thử ngoài Claude Code, chạy bảng điều khiển trong terminal:

```bash
npx ruflo tui
```

Thêm `--plain` để in ra một khung hình duy nhất, tiện cho script:

```bash
npx ruflo tui --plain
```

README không đưa ra mẫu kết quả cụ thể cho lệnh này. Nếu terminal không báo lỗi và hiện giao diện, coi như chạy được.

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

### Rà soát một repo và viết test cho chỗ yếu nhất

Bạn là lập trình viên nhận lại dự án cũ, không biết chỗ nào dễ hỏng. Chạy `npx ruflo@latest init` trong dự án, mở Claude Code rồi dán câu mẫu của README (Use a ruflo swarm to review this repo...). Mong đợi theo README: swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Hãy đọc kỹ phần tóm tắt và chạy test trước khi nhận thay đổi.

> Đừng học hết 406 công cụ. Chạy init, rồi cứ dùng Claude Code như bình thường.
>
> — Ông T

### Cho Claude tạo một mission, mình vẫn giữ quyền duyệt

Bạn muốn thử Claude điều khiển bảng console mà không sợ nó làm bậy. README hướng dẫn:

1. Cài console, mở `/ruflo`, vào **Settings → Claude control** và chọn **write + ask**.
2. Nhờ Claude: "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 đang chờ.
4. Kiểm tra mục Missions có mục tiêu và Overview 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 viết. Bấm **Take back control** bất cứ lúc nào để dừng Claude điều khiển.

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

Bạn dùng Codex hơn Claude Code. Bạn khai báo MCP server với command `npx` và arguments `-y ruflo@latest mcp start` như phần cài đặt ở trên. Sau đó công cụ của ruflo (bộ nhớ, swarm, agent) có thể được gọi từ chính ứng dụng đó. README không mô tả kịch bản chi tiết cho Codex, nên bạn nên thử trên dự án nhỏ trước.

### Theo dõi chi phí và tạo test bằng plugin lẻ

Bạn không muốn cài cả bộ vào dự án, chỉ muốn thử một món. Dùng cách plugin: thêm marketplace bằng `/plugin marketplace add ruvnet/ruflo`, rồi cài thứ bạn cần, chẳng hạn `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí) hoặc `ruflo-testgen` (tìm test còn thiếu và sinh test). README ghi mẫu lệnh cài cho `ruflo-core`, `ruflo-swarm`, `ruflo-rag-memory`, nên với plugin khác bạn làm tương tự: `/plugin install tên-plugin@ruflo`, rồi `/reload-plugins`.

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

**Lệnh `/plugin` hoặc `/ruflo` không nhận.** Rất có thể Claude Code của bạn cũ. Cách plugin cần 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 rồi chạy `/reload-plugins` hoặc mở lại.

**`npx` báo lỗi hoặc không chạy.** `package.json` yêu cầu Node 20 trở lên. Kiểm tra phiên bản bằng `node --version` và nâng cấp nếu thấp hơn.

**Đã chạy `init` mà Claude Code không thấy agent hay công cụ mới.** README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy thoát hẳn rồi mở lại, và đảm bảo bạn mở đúng thư mục đã chạy `init`.

**Plugin bị nạp hai lần.** Với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`, README cảnh báo chỉ cài từ một marketplace, vì cài từ cả hai thì mod và lệnh sẽ nạp đôi.

**Tên công cụ MCP khác với tài liệu.** Cách plugin đăng ký công cụ dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, trong khi cách cài bằng CLI dùng tên trần như `memory_store`. Nếu làm theo hướng dẫn mà gọi sai tên, hãy kiểm tra bạn đang dùng cách cài nào.

**Claude từ chối một thao tác trong console.** Thao tác vượt mức quyền bạn đã cấp sẽ bị từ chối. Đó là thiết kế an toàn, không phải lỗi. Nếu thật sự cần, hãy tự nâng mức quyền trong Settings, nhưng nên nhớ mặc định hiện là read + ask.

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

**Điểm mạnh.** Cài chỉ một lệnh. Có sẵn rất nhiều agent, plugin và console theo dõi chi phí. Có giới hạn quyền rõ ràng khi cho Claude điều khiển. Hỗ trợ cả Claude Code, Codex và các ứng dụng MCP. Giấy phép MIT và repo còn hoạt động.

**Giới hạn.** Repo rất lớn (hàng trăm công cụ MCP, hàng chục lệnh, 48 plugin), nên người mới dễ choáng. README cũng thừa nhận một số hình minh hoạ dùng dữ liệu mẫu, không chứng minh swarm hay bộ nhớ đã làm xong việc thật. Phần học tự động vẫn cần embedding và module được cấu hình. Các mod chạy với quyền tài khoản của bạn và không được cô lập. Tài liệu chưa nói gì về chi phí token khi chạy nhiều agent, nên bạn hãy tự theo dõi.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần trợ lý trả lời và sửa code một file vài lần mỗi tuần, Claude Code đơn thuần là đủ. Nếu chỉ cần một tính năng nhỏ (ví dụ theo dõi chi phí), hãy cài đúng một plugin thay vì cả bộ. Nếu bạn lo về chuyện file bị ghi vào dự án, dùng cách plugin (không thêm file) hoặc thử trên bản sao trước.

## 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 code tự do. Tư liệu không nói gì về chi phí khi chạy agent. Bạn vẫn trả phí cho dịch vụ AI bên dưới (như Claude Code hoặc Codex) theo gói của chính bạn.

### ruflo khác gì Claude Code?

Claude Code là công cụ AI lập trình. ruflo là lớp điều phối đặt quanh nó (và Codex), thêm agent chuyên biệt, swarm, bộ nhớ, hook và bảng điều khiển. Bạn vẫn làm việc trong Claude Code, ruflo thêm các khả năng này vào.

### Cần cài những gì để chạy ruflo?

Theo tư liệu, bạn cần Node.js 20 trở lên và Claude Code (hoặc Codex hay ứng dụng MCP khác). Với cách plugin cần Claude Code từ 2.1.287 trở lên. README không nói gì về yêu cầu GPU hay phần cứng riêng.

### 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: README nói lệnh này thêm .claude/, .claude-flow/, CLAUDE.md và các file hỗ trợ vào dự án. Nếu không muốn thêm file nào, dùng cách chỉ cài plugin trong Claude Code, cách này không đặt file vào workspace.

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

Tư liệu không nêu rõ danh sách hệ điều hành được hỗ trợ. Điều có thể chắc chắn là gói cần Node 20 trở lên và chạy bằng npx. Bạn nên thử trên dự án nháp để kiểm tra.

### Dùng ruflo có an toàn không?

README nói 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 code trước khi cài. Khi cho Claude điều khiển console, mặc định hiện là read + ask, và các thao tác mạng, tốn tiền, phá huỷ vẫn phải xác nhận. Tư liệu không cho biết thêm về cách dữ liệu được lưu hay gửi đi.

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

Được. README ghi Codex và các ứng dụng MCP khác dùng được bằng cách trỏ tới lệnh npx -y ruflo@latest mcp start, hoặc chạy npx ruflo@latest init wizard để thiết lập dự án có hỏi đáp. Chi tiết cấu hình theo từng ứng dụng thì README chưa nói.
