# Ruflo: điều phối nhóm agent cho Claude Code và Codex — hướng dẫn cài đặt và dùng

> Ruflo là một "agent meta-harness": lớp công cụ đặt quanh Claude Code và Codex để thêm agent chuyên biệt, bộ nhớ qua nhiều phiên, hook tự động và máy chủ MCP. Bạn dùng nó để Claude Code làm việc theo nhóm thay vì từng agent riêng lẻ. Cài khá đơn giản: chạy một lệnh npx trong thư mục dự án, cần Node 20 trở lên.

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

Ruflo là một bộ khung (harness) đặt quanh Claude Code và Codex. README gọi nó là "agent meta-harness". Nói đơn giản: mô hình AI viết code, còn Ruflo cung cấp công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát để mô hình làm việc được như một nhóm.

Bạn nên xem repo này nếu đang dùng Claude Code hoặc Codex và muốn nhiều hơn một agent trả lời từng câu. Ruflo thêm hơn 100 agent chuyên biệt, các "swarm" (nhóm agent phối hợp), bộ nhớ tự học giữa các phiên, và cả liên kết agent giữa nhiều máy. Dự án hiện có khoảng 81.588 sao và 9.608 fork trên GitHub, giấy phép MIT, và vẫn được cập nhật trong ba tháng gần đây.

Điểm đáng giá nhất là cách vào cửa rất nhẹ: một lệnh `npx ruflo@latest init` trong thư mục dự án. Sau đó bạn cứ dùng Claude Code như bình thường, các hook sẽ tự định tuyến tác vụ và phối hợp agent ở phía sau. Bài này hướng dẫn cài, kiểm tra và dùng vào vài việc cụ thể, bám đúng những gì README nói.

```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à máy chủ MCP, chỉ cần một lệnh npx để cài.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Ruflo không phải một ứng dụng riêng. Nó là lớp "hệ thần kinh" gắn vào công cụ bạn đang dùng. Các phần chính:

- **Agent và swarm.** Hơn 100 agent chuyên biệt tự tổ chức thành nhóm. Bạn giao một việc lớn, các agent chia nhau làm. README mô tả luồng khái quát: người dùng → Ruflo (CLI/MCP) → bộ định tuyến → swarm → agent → bộ nhớ → nhà cung cấp mô hình.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ lại kinh nghiệm từ những lần làm trước và dùng để định tuyến tốt hơn. README lưu ý đâ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.
- **Hook tự động.** Sau `init`, bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Hook tự định tuyến tác vụ và học từ những mẫu thành công.
- **Máy chủ MCP.** Codex và các ứng dụng khách MCP khác có thể trỏ vào Ruflo để dùng chung công cụ.
- **Liên kết (federation).** Agent trên các máy khác nhau nói chuyện với nhau một cách an toàn, theo README là không làm rò rỉ dữ liệu.
- **Bảng điều khiển (console / cockpit).** Một giao diện cạnh Claude Code để theo dõi workflow, agent, mô hình, token và chi phí; xem log, tìm kiếm, phát lại và so sánh các lần chạy.
- **Chợ plugin.** Có 48 plugin (cộng 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps... Ví dụ `ruflo-testgen` tìm test còn thiếu và tạo test, `ruflo-cost-tracker` theo dõi token và đặt ngân sách.

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

Tư liệu nêu những điều sau:

- **Node.js 20.0.0 trở lên** (theo package.json). Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn dùng cách cài trọn bộ hoặc cách plugin. Cách chỉ cài plugin cần Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` từ terminal cần **2.1.292 trở lên**.
- Nếu dùng **Codex** hay ứng dụng khách MCP khác, bạn chỉ cần cấu hình lệnh chạy máy chủ MCP (xem bước sau).

README phần đã cho không nói về yêu cầu GPU, hệ điều hành cụ thể hay API key riêng cho Ruflo. Phần này chưa có thông tin; bạn xem thêm trong thư mục `docs/` của repo hoặc hướng dẫn người dùng mà README trỏ tới. Lưu ý Claude Code và các mô hình bạn dùng phía sau có thể cần tài khoản riêng của chúng.

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

README có ba đường: cài trọn bộ bằng `npx`, cài chỉ plugin trong Claude Code, hoặc cấu hình cho Codex/MCP. Bạn chọn một. Với người mới, mình khuyên đường đầu tiên.

```steps
- Mở terminal đúng chỗ | 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
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao thử một việc | Đưa cho Claude Code một tác vụ thật có nhắc đến swarm
- (Tuỳ chọn) Dùng cách khác | Cài plugin, nối Codex qua MCP, hoặc chạy giao diện terminal
```

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

Đây là chỗ người mới hay vấp. `init` ghi file vào thư mục hiện tại, nên bạn phải đứng đúng thư mục dự án trước khi chạy. Nếu chưa có dự án, hãy tạo một thư mục thử nghiệm riêng.

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

Thay `duong-dan-toi-du-an-cua-ban` bằng đường dẫn thật trên máy bạn.

### Chạy lệnh init

Đây là lệnh chính trong README:

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

Lệnh này 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, cách này tạo thêm `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và file cài đặt trong dự án. Vì vậy nếu dự án đã có `CLAUDE.md`, bạn nên sao lưu hoặc dùng quản lý phiên bản (git) để xem lại thay đổi.

Nếu muốn thiết lập theo kiểu hỏi đáp, README ghi có lệnh:

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

```note
Init ghi file vào thư mục dự án. Hãy chạy thử trên dự án có git hoặc thư mục sao lưu để xem được chính xác những gì đã thay đổi.
```

### Mở Claude Code và giao việc

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thành phần mới ở lần khởi động kế tiếp, nên nếu Claude Code đang mở sẵn, hãy thoát ra rồi mở lại. Sau đó thử 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.
```

### 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" chạy trong Claude Code. Gõ các lệnh sau bên 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
```

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

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

README cảnh báo: các mod chạy với quyền của tài khoản bạn và không bị đưa vào sandbox, nên hãy đọc mã trước khi cài.

Bảng so sánh trong README cũng nói rõ: cách plugin là bản "lite", chỉ có lệnh gạch chéo, vài kỹ năng và định nghĩa agent, không có hook và chỉ đăng ký máy chủ MCP nếu có `ruflo-core`. Muốn trọn vòng lặp như tài liệu mô tả thì dùng `npx ruflo@latest init`.

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

Không cần thiết lập dự án. Trong phần cấu hình MCP của ứng dụng, đặt **command** là `npx` và **arguments** là:

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

README cũng ghi dạng lệnh đầy đủ tương đương là `npx -y ruflo@latest mcp start`.

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

Bảng điều khiển chạy được độc lập, không cần Claude Code:

```bash
npx ruflo tui
```

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

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

Theo README, có vài dấu hiệu để biết cài xong:

- Sau `npx ruflo@latest init` và khởi động lại Claude Code, gõ `/ruflo` sẽ mở bảng điều khiển.
- Trong thư mục dự án xuất hiện `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Nếu cài bằng plugin, mở `/plugin` và kiểm tra các plugin xuất hiện trong dòng "active mods".
- Với `npx ruflo tui`, giao diện bảng điều khiển hiện ngay trong terminal.

README không nêu một dòng "kết quả mong đợi" cụ thể cho lệnh `init`. Nếu không thấy thay đổi gì, xem thư mục `docs/` hoặc phần hướng dẫn người dùng của repo.

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

### Rà soát một repo và viết test cho chỗ rủi ro nhất

Bối cảnh: bạn là lập trình viên mới, vừa nhận một dự án cũ và chưa biết đụng vào đâu. Sau khi chạy `init` và mở lại Claude Code, bạn đưa đú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: một nhóm agent cùng tìm module rủi ro nhất, viết test cho nó, rồi tóm tắt những gì đã đổi. Bạn đọc bản tóm tắt và xem lại thay đổi trong git trước khi giữ lại.

> Agent = Model + Harness. Mô hình viết, còn bộ khung lo công cụ, bộ nhớ và kiểm soát để nó làm việc được thật.
>
> — Ông T

### Theo dõi công việc trong bảng điều khiển

Bối cảnh: bạn muốn thấy agent đang làm gì, tốn bao nhiêu token và chi phí. Sau khi cài, mở Claude Code và gõ:

```text
/ruflo
```

Bảng điều khiển hiển thị workflow, agent, mô hình, token và chi phí cạnh Claude Code. Bạn có thể mở log, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Hợp với người quản lý nhóm nhỏ muốn biết agent làm gì mà không phải đọc từng dòng log thô.

### Để Claude điều khiển bảng điều khiển, nhưng bạn đặt giới hạn

Bối cảnh: bạn muốn thử giao việc quản lý cho Claude. README mô tả cách làm an toàn từng bước: vào **Settings → Claude control**, 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**. Chọn **write + ask**, rồi nhờ:

```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 xác nhận thao tác tạo. Kiểm tra bằng cách xem Missions có mục tiêu mới và Overview có ghi lại hành động. README nhấn mạnh: tạo một mission không có nghĩa là tính năng đã được làm. Muốn dừng, bấm **Take back control**.

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

Bối cảnh: bạn không dùng Claude Code mà dùng Codex. Cấu hình MCP với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]` như phần trên. Công cụ của Ruflo sẽ xuất hiện trong ứng dụng khách MCP đó mà không phải thiết lập thêm trong dự án. README không liệt kê chi tiết từng công cụ ở phần đã cho, nên hãy xem danh sách công cụ trong chính ứng dụng của bạn sau khi nối.

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

README phần đã cho không có mục xử lý sự cố. Dưới đây là các lỗi rất dễ gặp với loại công cụ này, kèm cách xử lý an toàn.

**Lệnh `npx` báo lỗi hoặc không chạy.** Kiểm tra phiên bản Node bằng `node --version`. package.json yêu cầu Node 20.0.0 trở lên; nếu thấp hơn, hãy nâng cấp Node rồi chạy lại.

**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 trong đúng thư mục đã chạy `init`. Với cách plugin, gõ `/reload-plugins` rồi kiểm tra `/plugin`.

**Lệnh `/plugin install` không được.** Cách plugin cần Claude Code 2.1.287 trở lên (lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên). Hãy cập nhật Claude Code trước.

**Cài `agentdb` hoặc plugin ngoài từ hai chợ cùng lúc.** README cảnh báo với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb` và `agentic-flow`: chỉ cài từ một chợ, nếu bật cả hai thì mod và lệnh bị nạp hai lần. Hãy gỡ một bên.

**Claude làm quá phạm vi bạn muốn.** Giữ mặc định read + ask trong Claude control và chỉ nâng quyền khi cần. README nói các hành động mạng, chi tiền và phá huỷ vẫn cần xác nhận ngay cả ở chế độ `auto`. Có thể bấm **Take back control** bất cứ lúc nào.

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

**Điểm mạnh.**

- Cài nhanh, một lệnh, giấy phép MIT.
- Hỗ trợ nhiều đường vào: Claude Code, Codex, ứng dụng khách MCP khác, và cả giao diện terminal riêng.
- Có sẵn bảng điều khiển để theo dõi agent, token và chi phí.
- Có cơ chế giới hạn quyền cho Claude khi điều khiển bảng điều khiển.

**Giới hạn.**

- Hệ sinh thái rất lớn (hàng chục plugin, hàng trăm công cụ MCP). Người mới dễ choáng; hãy bắt đầu bằng `init` và một tác vụ thật.
- Cách `init` ghi nhiều file vào dự án. Bạn cần quản lý phiên bản để kiểm soát thay đổi.
- README tự nói nhiều đoạn minh hoạ chỉ là mô hình khái niệm hoặc dữ liệu mẫu, không phải bằng chứng một swarm đã hoàn tất công việc hay bộ nhớ đã được gọi lại. Hãy tự kiểm chứng kết quả trên dự án của bạn.
- Các mod chạy với quyền tài khoản và không có 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 từng câu hỏi lẻ trong một file nhỏ, bản Claude Code thuần là đủ và nhẹ hơn. Ruflo đáng thử khi bạn có việc nhiều bước, muốn nhiều agent phối hợp, muốn bộ nhớ qua nhiều phiên và cần theo dõi chi phí. Nếu chỉ muốn thử vài lệnh mà không thêm file vào dự án, hãy chọn cách cài plugin.

## 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 và sửa được tự do. Tư liệu không nói gì về chi phí của các mô hình hay dịch vụ phía sau như Claude Code hay Codex, nên bạn cần tự kiểm tra gói tài khoản của chúng. Ruflo có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

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

Tư liệu phần đã cho chưa nêu rõ hệ điều hành được hỗ trợ. Yêu cầu duy nhất được ghi là Node.js 20.0.0 trở lên. Bạn nên thử trên dự án nhỏ hoặc xem thêm trong thư mục docs của repo.

### Cần GPU không?

Phần README đã cho không nhắc yêu cầu GPU cho cách cài cơ bản. Chỉ có mô tả plugin ruflo-ruvector là tìm kiếm tăng tốc bằng GPU, và đó là plugin tuỳ chọn. Với dùng cơ bản bằng npx ruflo@latest init, chưa có thông tin cần GPU.

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

Claude Code là công cụ để mô hình viết và sửa code. Ruflo là lớp harness bao quanh nó, thêm hơn 100 agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook tự động và máy chủ MCP. Bạn vẫn dùng Claude Code như bình thường, Ruflo phối hợp ở phía sau.

### Dữ liệu của tôi có an toàn không?

README nói có các lớp kiểm soát bảo mật cho doanh nghiệp và federation giữa các máy mà không làm lộ dữ liệu. Bảng điều khiển có mức quyền read/write/manage/full và hành động nhạy cảm vẫn cần xác nhận. Tuy vậy các mod chạy với quyền tài khoản của bạn và không có sandbox, nên cần đọc mã trước khi cài.

### Dùng với Codex hoặc công cụ khác ngoài Claude Code được không?

Được. README ghi Codex và ứng dụng khách MCP khác dùng được: cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Có thêm tuỳ chọn init --grok cho Grok Build, và lệnh npx ruflo tui để chạy giao diện terminal riêng.

### Nên chọn cài bằng npx init hay bằng plugin?

Theo README, npx ruflo@latest init cho trọn vòng lặp (agent, lệnh, kỹ năng, máy chủ MCP, hook, daemon) nhưng ghi file vào dự án. Cách plugin không thêm file nào vào dự án nhưng chỉ có lệnh gạch chéo, vài kỹ năng và định nghĩa agent, không có hook. README gợi ý cách init cho việc dùng thật, plugin để thử từng phần.
