# 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 agent phối hợp, có bộ nhớ và có hooks. Bạn chỉ cần chạy một lệnh npx trong thư mục dự án rồi mở lại Claude Code. Cài đặt không khó, nhưng repo rất lớn nên nên bắt đầu từ các bước đơn giản.

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

ruflo là một «agent harness» (bộ khung điều phối) bao quanh Claude Code và Codex. Hiểu đơn giản: mô hình AI là người viết, còn ruflo là bàn làm việc đầy đủ đồ nghề quanh người đó: công cụ, bộ nhớ, vòng lặp kiểm tra và các lớp kiểm soát. Nhờ vậy nhiều agent có thể cùng làm một việc thay vì mỗi con chạy một mình.

Repo này dành cho ai đã dùng Claude Code hoặc Codex và muốn đi xa hơn một cuộc trò chuyện đơn lẻ: giao một việc lớn cho cả «đội» agent, để chúng nhớ lại kinh nghiệm giữa các phiên. Người làm kinh doanh hay văn phòng cũng dùng được nếu có Claude Code, nhưng bạn nên quen việc mở terminal trước.

Điểm đáng giá nhất là độ dễ vào cửa: một lệnh `npx ruflo@latest init` là xong phần cài. README nói rõ bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Sau `init`, bạn cứ dùng Claude Code như bình thường, hệ thống hooks sẽ tự định tuyến việc và phối hợp agent ở phía sau. Hiện repo có khoảng 81.600 sao và khoảng 9.600 fork, giấy phép MIT.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung điều phối bao quanh Claude Code và Codex: thêm agent, bộ nhớ, hooks và máy chủ MCP vào dự án chỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những điều chính, theo cách README mô tả.

- **Đội agent làm việc theo nhóm (swarm).** Repo nói có hơn 100 agent chuyên biệt, tự tổ chức thành swarm. Bạn giao một việc lớn, các agent chia nhau làm thay vì một agent ôm hết.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ được thứ đã làm ở lần trước và học từ các việc thành công. README lưu ý đây là vòng học mang tính khái niệm: truy xuất 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.
- **Hooks tự động.** Sau `init`, hooks tự định tuyến tác vụ và phối hợp agent ngầm, bạn không phải gọi từng công cụ.
- **Máy chủ MCP.** Claude Code, Codex hay client MCP khác đều nối vào được. Cách nối: lệnh `npx -y ruflo@latest mcp start`.
- **Bảng điều khiển (console) ngay cạnh Claude Code.** Theo dõi workflow, agent, mô hình, token và chi phí. Bạn xem được 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.
- **Cho Claude lái, bạn đặt giới hạn.** Mục Settings → Claude control cho Claude điều khiển console theo mức `read`, `write`, `manage` hoặc `full`, với chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các hành động vượt quyền bị từ chối; hành động liên quan mạng, chi tiền hay phá huỷ vẫn phải xác nhận ngay cả khi ở `auto`.
- **Kho plugin.** README liệt kê 48 plugin (kèm 3 plugin bên ngoài): swarm, bộ nhớ RAG, tạo test, quét bảo mật, theo dõi chi phí, tài liệu tự động và nhiều nhóm khác. Bạn cài lẻ từng cái nếu chỉ cần một vài thứ.
- **Liên kết nhiều máy (federation).** Agent trên các máy khác nhau trao đổi với nhau, README nói là không làm lộ dữ liệu.

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

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

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

Tư liệu chưa nói rõ về yêu cầu hệ điều hành, phần cứng hay API key cụ thể cho từng bước. Vì vậy mình không đoán: nếu cần, bạn xem thêm trong tài liệu `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ị đưa vào sandbox. README khuyên đọc mã của chúng trước khi cài. Hãy làm đúng như vậy, nhất là trên máy có dữ liệu công việc thật.
```

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

README có hai đường chính. Đường thứ nhất (CLI) cho đầy đủ nhất, mình khuyên bạn chọn đường này.

```steps
- Mở terminal | Vào đúng thư mục dự án của bạn
- Chạy init | Lệnh npx ruflo@latest init thêm agent, hooks, bộ nhớ, MCP vào dự án
- Mở lại Claude Code | Mở trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thật | Dán một câu lệnh mẫu nhờ dùng swarm
- Tuỳ chọn: cài console | Dùng plugin để có bảng điều khiển /ruflo
```

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

Lỗi người mới hay gặp nhất là chạy lệnh ở sai chỗ. `init` ghi file vào thư mục hiện tại, nên bạn phải đứng trong dự án của mình. Ví dụ trên Windows PowerShell hoặc macOS/Linux terminal:

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

Hãy thay `ten-thu-muc-du-an-cua-ban` bằng đường dẫn thư mục của bạn.

### Chạy lệnh init

Đây là lệnh chính của README:

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

`npx` tải ruflo bản mới nhất rồi chạy. `init` thêm agent, hooks, bộ nhớ và máy chủ MCP vào dự án. README cho biết thư mục dự án sẽ có thêm `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng các file hỗ trợ và settings. Vì vậy nếu dự án của bạn đang dùng git, bạn nên commit trước để dễ xem ruflo đã thêm gì.

Nếu muốn cài theo kiểu hỏi đáp từng bước, 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ác thứ mới ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code từ trước thì hãy thoát ra và mở lại.

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

Sau khi mở lại, thử với 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âu này nhờ Claude dùng swarm để rà soát dự án, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi.

### Đường khác: chỉ cài plugin cho Claude Code

Nếu không muốn thêm file vào dự án, README có đường «plugin only». Đường này không thêm file nào vào dự án, nhưng ít tính năng hơn bản CLI (ví dụ không cài hooks). Bạn gõ 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
```

Lần lượt: thêm kho plugin của ruflo, cài lõi, cài bảng điều khiển, cài mod, nạp lại plugin, rồi mở console bằng `/ruflo`. Nếu dùng Claude Code 2.1.292 trở lên, bạn có thể cài từ terminal:

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

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

README hướng dẫn cấu hình client với **command** là `npx` và **arguments** là:

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

Chỗ điền cấu hình này phụ thuộc vào client bạn dùng. Tư liệu không nêu cụ thể cho từng client, nên bạn xem mục cấu hình MCP của chính client đó.

### Chạy console ngoài Claude Code

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

```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

Tuỳ đường cài, bạn có các dấu hiệu sau:

- **Đường CLI:** sau `init`, trong thư mục dự án phải có `.claude/`, `.claude-flow/` và `CLAUDE.md`. Mở lại Claude Code rồi gõ `/ruflo` để mở console.
- **Đường plugin:** gõ `/plugin` trong Claude Code và xem các mod đã cài có xuất hiện ở dòng «active mods» hay không. Gõ `/ruflo` để mở console.
- **Thử một việc nhỏ:** trong console, vào Settings → Claude control và chọn **write + ask**. Rồi bảo Claude: «Create a mission to add a dark mode toggle. Show me the mission and its status.» Xác nhận hành động tạo khi console hỏi. Nếu mục Missions có mục tiêu đó và Overview ghi lại hành động, nghĩa là cầu nối hoạt động. README nhấn mạnh: tạo mission không có nghĩa tính năng dark mode đã được viết.

Tư liệu chưa mô tả một dòng chữ «thành công» cố định ở terminal sau `init`, nên mình không hứa một thông báo cụ thể nào.

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

### Dev nhận lại một dự án lạ

Bạn mới vào một dự án cũ, không biết đâu là chỗ dễ hỏng. Sau khi `init` và mở lại Claude Code, dán câu mẫu:

```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 theo README: agent chỉ ra module rủi ro nhất, viết test cho nó và có bản tóm tắt thay đổi. Bạn vẫn cần tự đọc lại test trước khi dùng.

> Bạn không cần học 406 công cụ. Cài xong, cứ dùng Claude Code như thường, phần điều phối để ruflo lo.
>
> — Ông T

### Người quản lý muốn nhìn rõ agent đang làm gì

Bạn giao việc cho AI nhưng không biết nó đang chạy gì, tốn bao nhiêu token. Cài `ruflo-console` bằng plugin, mở `/ruflo`. Bạn xem được workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code, mở log để xem kết quả và dò lỗi. Với người không đọc code, đây là chỗ dễ hiểu nhất của ruflo.

### Giao quyền có kiểm soát

Bạn muốn Claude tự thao tác trong console nhưng không muốn nó làm bừa. Vào Settings → Claude control, chọn `write` và duyệt `ask`. Mỗi hành động tạo mới sẽ hỏi bạn. Nếu thấy không ổn, bấm **Take back control** để dừng ngay. README nói sau khi lấy lại quyền, lời gọi tiếp theo của Claude sẽ bị từ chối cho tới khi bạn khôi phục.

### Nối Codex hoặc client MCP khác

Bạn dùng Codex thay vì Claude Code. Cấu hình client chạy `npx` với tham số `["-y", "ruflo@latest", "mcp", "start"]`. Khi đó client của bạn dùng được các công cụ MCP của ruflo mà không cần cài vào dự án. Tư liệu không cho ví dụ kết quả cụ thể cho Codex, nên bạn tự thử bằng một việc nhỏ trước.

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

**Lệnh npx báo lỗi hoặc không chạy.** Rất có thể Node của bạn cũ. ruflo yêu cầu Node từ 20.0.0 trở lên. Kiểm tra bằng `node --version` rồi nâng cấp Node nếu cần.

**Claude Code không thấy gì sau `init`.** 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 và mở lại trong đúng thư mục đã chạy `init`.

**Lệnh `/plugin` không nhận hoặc cài plugin thất bại.** Đường plugin cần Claude Code 2.1.287 trở lên (lệnh cài từ terminal cần 2.1.292 trở lên). Hãy cập nhật Claude Code rồi chạy `/reload-plugins`.

**Plugin chạy hai lần, lệnh bị trùng.** README cảnh báo với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`: chỉ cài từ một kho duy nhất. Bật từ cả hai kho thì mod và lệnh nạp hai lần.

**Claude từ chối hành động trong console.** Đây không phải lỗi: hành động vượt mức quyền bạn chọn sẽ bị từ chối. Nếu thật sự cần, hãy nâng mức quyền một cách có ý thức. Hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần xác nhận.

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

**Điểm mạnh.** Cài nhanh (một lệnh), giấy phép MIT, nhiều lựa chọn (CLI, plugin, MCP, console độc lập), có lớp kiểm soát quyền khá rõ, và repo vẫn được cập nhật trong 3 tháng gần đây. Phần console giúp người không chuyên nhìn thấy agent đang làm gì.

**Giới hạn.** Repo rất lớn: hàng trăm công cụ, hàng chục plugin, nhiều khái niệm như swarm, federation, vector RAG. Người mới dễ choáng. README cũng tự thừa nhận vài điểm: vòng học là khái niệm, các bản demo dùng dữ liệu mẫu và không chứng minh việc swarm đã hoàn thành công việc thật. Bản CLI thêm khá nhiều file vào dự án, còn bản plugin thì ít tính năng hơn. Các mod không bị sandbox.

**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 hay sửa một file nhỏ, bạn chưa cần ruflo. Nếu thích thử nhẹ nhàng, hãy chỉ cài `ruflo-core` bằng plugin trước, hoặc chạy trên một dự án thử. Khi thấy hữu ích mới chuyển sang `npx ruflo@latest init` đầy đủ.

## 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 mã nguồn tự do. Tư liệu chưa nói về chi phí của các dịch vụ đi kèm như Claude Code hay nhà cung cấp mô hình AI. Plugin ruflo-cost-tracker giúp theo dõi token và đặt ngân sách.

### ruflo cần cài gì trước?

Cần Node.js từ 20.0.0 trở lên và một client như Claude Code hoặc Codex. Nếu cài plugin trong Claude Code thì cần bản 2.1.287 trở lên. Tư liệu chưa nêu yêu cầu về phần cứng hay GPU.

### Cài ruflo như thế nào là nhanh nhất?

Mở terminal trong thư mục dự án và chạy npx ruflo@latest init, rồi mở lại Claude Code. Lệnh này thêm agent, hooks, bộ nhớ và máy chủ MCP vào dự án. Nếu không muốn thêm file, bạn có thể cài plugin bằng lệnh /plugin trong Claude Code.

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

Có. README nói Codex và các client MCP khác dùng được: cấu hình command là npx với arguments là ["-y", "ruflo@latest", "mcp", "start"]. Chỗ điền cấu hình tuỳ client, tư liệu chưa hướng dẫn chi tiết.

### Claude có tự ý làm bừa trong console ruflo không?

Không nếu bạn giữ cài đặt mặc định. Mức mặc định hiện là read + ask. Hành động vượt mức quyền bị từ chối, còn hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần bạn xác nhận. Bạn có thể bấm Take back control để dừng ngay.

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

Claude Code thuần là mô hình cộng công cụ cơ bản. ruflo thêm lớp harness bên ngoài: nhiều agent chuyên biệt, swarm, bộ nhớ qua các phiên, hooks tự định tuyến, console theo dõi và kho plugin. Tư liệu chưa có số liệu so sánh hiệu quả cụ thể.

### Các mod của ruflo có an toàn không?

README cảnh báo 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 mã trước khi cài. Về dữ liệu, tư liệu nói federation cho phép agent trên các máy nói chuyện mà không làm lộ dữ liệu, nhưng chưa có thêm chi tiết kiểm chứng.
