# 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 là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, thêm các agent chuyên biệt, bộ nhớ qua nhiều phiên, hooks và MCP server. Bạn dùng để giao việc lớn cho một nhóm agent phối hợp với nhau. Cài khá dễ: chỉ cần Node 20 trở lên và chạy `npx ruflo@latest init` trong thư mục dự án.

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

Ruflo là một "agent harness" mã nguồn mở: lớp công cụ đặt xung quanh Claude Code hoặc Codex để các AI này có thêm đội agent chuyên biệt, bộ nhớ lâu dài, hệ thống hooks và một MCP server. Repo này trước đây có tên Claude Flow. Mô hình AI vẫn là bên viết code. Ruflo lo phần còn lại: chia việc, nhớ lại những gì đã làm, và kiểm tra kết quả.

Bạn nên xem repo này nếu đang dùng Claude Code hoặc Codex cho dự án thật và thấy một cuộc trò chuyện đơn lẻ không đủ sức với việc lớn. Ví dụ: rà soát cả một repo, viết test cho nhiều module, hoặc làm việc nhiều ngày mà không muốn giải thích lại từ đầu. Lập trình viên mới cũng dùng được, vì README nói rõ sau khi cài bạn cứ dùng Claude Code như bình thường.

Đ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. Repo hiện có khoảng 81.588 sao và khoảng 9.608 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) bổ sung agent, bộ nhớ, hooks 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 đáng chú ý, theo cách README mô tả.

- **Đội agent chuyên biệt.** README nói Ruflo thêm hơn 100 agent chuyên biệt. Bảng so sánh cách cài ghi 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: thay vì một AI làm mọi thứ, bạn có thể giao từng phần cho agent phù hợp với phần đó.
- **Swarm (nhóm agent phối hợp).** Các agent tự tổ chức thành nhóm để cùng làm một nhiệm vụ. Bạn chỉ cần mô tả việc cần làm bằng ngôn ngữ thường.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ những gì đã làm ở lần trước. README cũng có các plugin về bộ nhớ như ruflo-agentdb, ruflo-rag-memory và ruflo-rvf (lưu và khôi phục bộ nhớ giữa các phiên).
- **Hooks tự động.** Sau khi cài, hooks tự định tuyến tác vụ, học từ các mẫu làm việc thành công và điều phối agent ở nền. Bạn không phải học thuộc hàng trăm công cụ. README nói rõ không cần học 406 công cụ MCP hay 61 lệnh CLI.
- **Bảng điều khiển (console).** Gõ `/ruflo` trong Claude Code để theo dõi workflow, agent, mô hình, token và chi phí. Bạn cũng mở được log của từng agent, tìm kiếm, phát lại và so sánh các lần chạy.
- **Cho Claude điều khiển bảng điều khiển, nhưng có giới hạn.** Trong Settings → Claude control, bạn chọn mức `read`, `write`, `manage` hoặc `full`, và chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các hành động tốn tiền, đụng mạng hoặc có tính phá hủy vẫn phải được bạn xác nhận, kể cả ở chế độ `auto`.
- **Hệ plugin.** README liệt kê 48 plugin, chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps, theo dõi chi phí... Ví dụ ruflo-testgen tìm test còn thiếu rồi tạo test, ruflo-cost-tracker theo dõi token và đặt ngân sách, ruflo-aidefence chặn prompt injection và phát hiện dữ liệu cá nhân.
- **Dùng được ngoài Claude Code.** Codex và các client MCP khác trỏ vào `npx -y ruflo@latest mcp start` là dùng được. Ngoài ra có giao diện terminal riêng.

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

Tư liệu chỉ nêu một số điều kiện rõ ràng:

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json`.
- **Claude Code** (hoặc Codex / client MCP khác). Với cách cài bằng plugin, README yêu cầu Claude Code **2.1.287 trở lên**. Lệnh cài plugin từ terminal cần Claude Code **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy `init`.

Về API key, tài khoản hay phần cứng, README đoạn đầu không nói bạn cần gì thêm ngoài việc dùng Claude Code hoặc Codex như bình thường. Về hệ điều hành, phần README được cung cấp cũng không nêu hạn chế nào. Phần README còn lại bị cắt nên mình không khẳng định thêm. Bạn có thể xem tiếp trong README của repo.

```note
Các mod của Ruflo chạy với quyền của tài khoản bạn và không được đưa vào sandbox. README khuyên đọc code trước khi cài. Hãy để chế độ Claude control ở mức read + ask khi mới làm quen.
```

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

```steps
- Kiểm tra Node | Đảm bảo máy có Node 20 trở lên
- Mở terminal đúng chỗ | Đứng trong thư mục dự án của bạn
- Chạy init | Thêm agent, hooks, bộ nhớ và MCP server vào dự án
- Mở lại Claude Code | Claude Code nạp cấu hình mới ở lần khởi động tiếp theo
- Giao việc thử | Gõ một yêu cầu thật để Ruflo vào việc
```

### Kiểm tra Node

Mở terminal và chạy lệnh dưới để xem phiên bản. Nếu số đầu nhỏ hơn 20, bạn cần cập nhật Node trước.

```bash
node --version
```

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

Chỗ này người mới hay vấp: `init` ghi file vào thư mục bạn đang đứng. Vì vậy hãy `cd` vào đúng dự án trước. Nếu chưa có dự án, bạn có thể tạo một thư mục thử.

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

### Chạy init

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

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

Lệnh này thêm agent, hooks, bộ nhớ và MCP server 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 helper và settings trong thư mục làm việc. Nếu bạn muốn xem trước khi ghi file với một số chế độ khác, README có nhắc cờ `--dry-run` cho nhánh `--grok`. Với `init` thường, README chưa ghi rõ cờ này, nên bạn đừng mặc định là có.

Muốn thiết lập tương tác từng bước, README ghi:

```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ành phần mới ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code, hãy thoát ra và mở lại.

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

Từ terminal, trên Claude Code 2.1.292 trở lên, README ghi lệnh:

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

README cho biết cách plugin chỉ cho bạn một phần: lệnh gạch chéo, vài skill và định nghĩa agent. Cách `init` mới là vòng chạy đầy đủ, gồm hooks, MCP server và daemon. Muốn dùng thật thì chọn `init`. Muốn thử một plugin lẻ thì chọn plugin.

### Cách khác: Codex hoặc client MCP

Cấu hình **command** là `npx` và **arguments** như sau:

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

Điền vào đâu thì tùy client của bạn. Mỗi client có chỗ khai báo MCP server riêng, và tư liệu chưa nói chi tiết.

### Cách khác: chạy giao diện terminal riê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

Không có một dòng "OK" chính thức nào trong tư liệu, nên bạn kiểm tra theo các dấu hiệu README nhắc tới:

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à dấu hiệu tốt.
3. Với cách cài plugin, mở `/plugin` và xem các plugin có xuất hiện trong dòng "active mods" không.
4. Trong bảng điều khiển, `/ruflo market` mở Plugin Catalog, nơi bạn thấy từng plugin, mod, skill và các nút cài, bật, tắt, cập nhật.

Nếu thiếu `.claude/` thì bạn nhiều khả năng đã chạy lệnh sai thư mục.

## 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 vừa nhận một dự án cũ, không có ai bàn giao. Sau khi `init` và mở lại Claude Code, bạn dùng đúng prompt mẫu trong 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: Claude Code dùng nhóm agent để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã sửa. Bạn đọc phần tóm tắt, chạy test và tự đánh giá lại.

> Mô hình viết code, còn Ruflo lo phần phối hợp. Bạn chỉ giữ quyền quyết định.
>
> — Ông T

### Thử bảng điều khiển với một nhiệm vụ nhỏ, an toàn

Bối cảnh: bạn quản lý một nhóm nhỏ và muốn xem AI làm việc trước khi tin nó. README có sẵn một kịch bản thử:

1. Cài console bằng các lệnh plugin ở trên, mở `/ruflo`, chọn **Settings → Claude control → write + ask**.
2. Gõ yêu cầu: "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 mission khi bảng điều khiển hỏi.
4. Kiểm tra mục Missions và Overview xem đã ghi lại chưa.

Lưu ý README nói rõ: tạo mission không có nghĩa là tính năng đã được làm. Bạn cũng có thể bấm **Take back control** để dừng quyền điều khiển của Claude bất cứ lúc nào.

### Làm việc nhiều ngày mà không phải giải thích lại

Bối cảnh: bạn làm một dự án kéo dài, mỗi sáng mở Claude Code lại phải kể lại từ đầu. Ruflo có bộ nhớ qua nhiều phiên và các plugin như ruflo-rvf (lưu và khôi phục bộ nhớ). Bạn cài `ruflo-rag-memory` hoặc `ruflo-agentdb` theo cách plugin, hoặc dùng `init` để có đủ bộ.

```text
/plugin install ruflo-rag-memory@ruflo
```

Kết quả mong đợi: agent có chỗ lưu và truy xuất lại kinh nghiệm cũ. README cũng lưu ý phần học này là "conceptual" và vẫn cần embedding cùng các module cấu hình, nên đừng kỳ vọng nó tự thần kỳ ngay lập tức.

### Theo dõi chi phí khi để agent chạy nhiều

Bối cảnh: bạn lo hoá đơn token tăng khi nhiều agent cùng chạy. README liệt kê plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí), còn bảng điều khiển hiển thị token và chi phí cạnh Claude Code.

```text
/plugin install ruflo-cost-tracker@ruflo
```

Kết quả: bạn có chỗ nhìn mức tiêu thụ trước khi giao việc lớn hơn.

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

**1. Node quá cũ.** `package.json` yêu cầu Node từ 20.0.0. Nếu `npx` báo lỗi lạ khi chạy, chạy `node --version` trước. Cập nhật Node rồi chạy lại.

**2. Chạy `init` nhầm thư mục.** File được ghi vào nơi bạn đang đứng. Nếu bạn lỡ chạy ở thư mục sai (ví dụ thư mục Home), hãy xem danh sách file mới tạo và dọn bằng tay cẩn thận. Cách an toàn hơn là thử trước trong một thư mục dự án mẫu.

**3. Claude Code không thấy Ruflo.** README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn Claude Code và mở lại trong đúng thư mục. Với cách plugin, chạy `/reload-plugins` rồi `/plugin` để kiểm tra.

**4. Lệnh `/plugin install` không chạy hoặc không có.** Cách plugin cần Claude Code 2.1.287 trở lên, còn lệnh cài từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước.

**5. Cài cùng một plugin ngoài từ hai marketplace.** README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow: nếu bật từ hai marketplace, mod và lệnh sẽ nạp hai lần. Chỉ cài từ một nguồn.

**6. Cho quyền quá cao.** Nếu nâng Claude control lên `full` + `auto`, bạn giao nhiều quyền hơn mức cần. Hãy bắt đầu bằng read + ask và chỉ nâng khi thật sự cần.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có sẵn nhiều agent, plugin và bảng điều khiển. Giấy phép MIT, dự án còn hoạt động. Bạn có thể chọn nhẹ (plugin, không thêm file) hoặc đầy đủ (`init`). Cơ chế quyền `read/write/manage/full` kết hợp `ask/auto` giúp bạn giữ kiểm soát.

**Giới hạn.** Repo rất lớn: 48 plugin, hàng trăm công cụ, nên người mới dễ choáng. Cứ bắt đầu từ `init` và một việc nhỏ. README tự nói bản demo dùng dữ liệu mẫu và không chứng minh việc swarm hay bộ nhớ đã hoàn thành công việc thật. Phần học tự động cũng được mô tả là khái niệm, còn cần cấu hình thêm. Các mod không chạy trong sandbox.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần một trợ lý viết code cho việc nhỏ lẻ, Claude Code hoặc Codex thuần đã đủ, không cần thêm lớp điều phối. Nếu bạn chỉ muốn vài lệnh gạch chéo, cài riêng một plugin sẽ gọn hơn. Còn nếu bạn làm dự án dài hơi và cần bộ nhớ, nhiều agent phối hợp cùng khả năng theo dõi chi phí, Ruflo đáng để thử trong một thư mục dự án thử nghiệm 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 mã nguồn dùng tự do. Tư liệu chưa nói về chi phí của các dịch vụ AI mà nó gọi tới. Bạn vẫn dùng Claude Code hoặc Codex theo gói của chính bạn, và có thể theo dõi chi phí qua bảng điều khiển hoặc plugin ruflo-cost-tracker.

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

Claude Code là công cụ AI viết code. Ruflo là lớp harness đặt quanh nó, thêm agent chuyên biệt, swarm, bộ nhớ, hooks và MCP server. Bạn vẫn dùng Claude Code như bình thường, Ruflo làm việc ở nền.

### Cài Ruflo cần những gì?

Theo package.json cần Node 20.0.0 trở lên. Cách cài plugin trong Claude Code cần Claude Code 2.1.287 trở lên. Lệnh cài plugin từ terminal cần 2.1.292 trở lên. Phần README được cung cấp không nêu yêu cầu GPU.

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

Có. README ghi Codex và các client MCP khác chạy được bằng cách cấu hình command là npx, arguments là ["-y", "ruflo@latest", "mcp", "start"]. Còn muốn thiết lập theo dự án thì chạy npx ruflo@latest init wizard.

### Cài plugin và chạy init khác nhau thế nào?

Cách plugin không thêm file nào vào dự án, chỉ cho lệnh gạch chéo, vài skill và định nghĩa agent. Cách init cho vòng chạy đầy đủ: agent, lệnh, skill, MCP server, hooks và daemon, đổi lại sẽ thêm file như .claude/ và CLAUDE.md vào thư mục dự án.

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

README mô tả cơ chế quyền: bạn chọn mức read, write, manage hoặc full và chế độ ask hoặc auto, mặc định là read + ask. Các hành động mạng, chi tiêu và phá hủy luôn cần xác nhận, và bạn có nút Take back control để dừng. 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 code trước khi cài.

### 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. Chỉ biết cần Node 20 trở lên và Claude Code. Bạn nên xem README đầy đủ trong repo hoặc thử trong một thư mục dự án mẫu trước.
