# 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à một agent harness mã nguồn mở, giấy phép MIT, giúp Claude Code và Codex làm việc theo nhóm agent, có bộ nhớ giữa các phiên và có hook tự định tuyến tác vụ. Bạn cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node từ 20 trở lên. Cài khá dễ, nhưng bộ tính năng rất rộng nên nên bắt đầu từ một tác vụ nhỏ.

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

Ruflo là một "agent meta-harness" cho Claude Code và Codex. Hiểu đơn giản: mô hình AI chỉ là bộ não biết viết code, còn Ruflo là bộ dụng cụ xung quanh nó. Bộ dụng cụ này gồm công cụ, bộ nhớ, vòng lặp kiểm tra và các lớp kiểm soát để AI làm việc được như một nhóm, thay vì một cuộc trò chuyện đơn lẻ.

Repo này dành cho người đã dùng Claude Code (hoặc Codex) và thấy một phiên chat đơn lẻ chưa đủ: quên bối cảnh khi mở phiên mới, khó chia việc lớn thành nhiều phần, khó theo dõi AI đang làm gì và tốn bao nhiêu token. Nếu bạn là lập trình viên mới, bạn vẫn dùng được, vì sau khi cài bạn cứ dùng Claude Code như bình thường. Hook của Ruflo sẽ tự định tuyến tác vụ ở phía sau.

Điều đáng giá nhất là cách vào cuộc rất nhẹ: một lệnh `npx ruflo@latest init`, mở lại Claude Code là xong. Hiện repo có khoảng 81588 sao và 9608 fork, được cập nhật trong 3 tháng gần đây. Phần còn lại của bài sẽ đi từ cài đặt đến vài tình huống dùng thật.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là lớp điều phối (harness) bọc quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server vào dự án chỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README giới thiệu rất nhiều thứ. Mình gom lại những phần bạn sẽ cảm nhận được ngay.

**Thêm đội agent vào dự án.** Sau `init`, dự án của bạn có sẵn các agent chuyên biệt, lệnh, skill, hook, bộ nhớ và một MCP server. README ghi bản cài đầy đủ gồm 98 agent, hơn 60 lệnh và 30 skill. Lợi ích: bạn không phải tự viết từng agent hay từng prompt dài để chia việc.

**Swarm, tức nhóm agent phối hợp.** Bạn có thể yêu cầu Claude dùng một swarm để xử lý việc lớn, ví dụ review cả repo. Các agent tự chia phần, rồi báo lại kết quả tổng hợp.

**Bộ nhớ qua nhiều phiên.** Ruflo có bộ nhớ vector (nhắc tới AgentDB, HNSW, RAG) để agent nhớ những gì đã làm. Mô tả của tác giả nói nó học từ các tác vụ thành công và đưa kinh nghiệm đó quay lại việc định tuyến. README cũng thận trọng ghi rõ đây là vòng học mang tính khái niệm. Việc 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 cấu hình.

**Bảng điều khiển (console) cạnh Claude Code.** Bạn theo dõi workflow, agent, model, token và chi phí. Bạn cũng mở được log từng lần chạy, tìm kiếm, xem lỗi, phát lại và so sánh. Mở bằng lệnh `/ruflo` trong Claude Code.

**Cho Claude lái, bạn đặt giới hạn.** Trong Settings có mục Claude control. Bạn chọn mức `read`, `write`, `manage` hoặc `full`, cùng chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các hành động liên quan mạng, chi tiêu hoặc phá hủy vẫn phải xác nhận kể cả khi ở `auto`.

**Kho plugin.** README liệt kê 48 plugin (cộng 3 plugin bên ngoài), chia nhóm: điều phối, bộ nhớ, học máy, chất lượng code và kiểm thử, bảo mật, DevOps, mở rộng. Ví dụ `ruflo-testgen` tìm chỗ thiếu test và sinh test, `ruflo-cost-tracker` theo dõi token và đặt ngân sách, `ruflo-security-audit` quét lỗ hổng.

**Chạy với client khác.** Codex hoặc client MCP bất kỳ đều nối được qua `npx -y ruflo@latest mcp start`. README còn có tuỳ chọn `npx ruflo init --grok` cho Grok Build.

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

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

- **Node.js từ phiên bản 20.0.0 trở lên** (package.json yêu cầu `node >=20.0.0`). Các lệnh đều dùng `npx`, đi kèm Node.
- **Claude Code** nếu bạn dùng đường cài đầy đủ. Nếu cài theo kiểu 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**.
- Hoặc **Codex / một client MCP khác** nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy lệnh `init`.

Tư liệu không nói rõ về hệ điều hành, yêu cầu GPU hay API key bắt buộc. Phần đó chưa có thông tin, bạn xem thêm trong tài liệu của repo trước khi dùng cho việc quan trọng. Lưu ý rằng bản thân Claude Code hay Codex của bạn vẫn cần tài khoản riêng để chạy mô hình.

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

README có nhiều đường cài. Mình đi theo đường chính (CLI) trước, rồi nói đường plugin và MCP.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án mà bạn muốn Ruflo hoạt động
- Chạy init | Dùng npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao một tác vụ thật | Gõ yêu cầu dùng swarm của ruflo
- (Tuỳ chọn) Cài console | Dùng plugin ruflo-console rồi gõ /ruflo
```

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

Chỗ người mới hay vấp nhất là chạy lệnh ở sai thư mục. `init` ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong dự án của mình. Nếu chưa có dự án, tạo một thư mục thử nghiệm để làm quen trước.

```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ật. Nếu muốn lấy mã nguồn Ruflo về xem, bạn có thể dùng lệnh clone, nhưng để dùng thì không cần:

```bash
git clone https://github.com/ruvnet/ruflo.git
```

### 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 bản mới nhất mà không cần cài toàn cục. README mô tả `init` sẽ thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh, bạn sẽ thấy các thứ như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file helper và settings xuất hiện trong thư mục. Nếu muốn thiết lập 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 trong cùng thư mục

Claude Code nhận cấu hình mới ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn một phiên, hãy đóng và mở lại trong đúng thư mục dự án. Rồi giao thử một việc thật:

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

Đây là câu mẫu của chính README. Bạn có thể giữ nguyên tiếng Anh hoặc diễn đạt lại bằng tiếng Việt cho việc của mình.

### Tuỳ chọn: cài bằng plugin, không thêm file vào dự án

Nếu bạn chỉ muốn thử và không muốn dự án có thêm file, README có đường plugin. Chạy bên trong Claude Code (cần 2.1.287 trở lên):

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

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

Đường này nhẹ hơn: không thêm file vào dự án, không cài hook. Với bản đầy đủ (98 agent, hook, daemon), README khuyên dùng `npx ruflo init`.

### Tuỳ chọn: Codex hoặc client MCP khác

Trong phần cấu hình MCP của client, đặt **command** là `npx` và **arguments** như sau:

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

Có thể viết gọn thành lệnh `npx -y ruflo@latest mcp start`. Cách điền cụ thể vào từng client thì README chưa ghi chi tiết, bạn xem tài liệu của client đó.

```note
Các mod của Ruflo chạy với quyền tài khoản của bạn và không có sandbox. README dặn đọc code trước khi cài. Hãy làm theo, nhất là khi cài thêm plugin từ nguồn ngoài.
```

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

Một vài dấu hiệu theo README:

1. Sau `npx ruflo@latest init`, thư mục dự án có thêm `.claude/`, `.claude-flow/` và file `CLAUDE.md`.
2. Mở lại Claude Code trong thư mục đó, nó nhận agent, hook và MCP server của Ruflo.
3. Nếu cài console, gõ `/ruflo` để mở bảng điều khiển. Với đường plugin, gõ `/plugin` và xem Ruflo có trong dòng "active mods".
4. Muốn thử console không cần Claude Code, chạy `npx ruflo tui`. Thêm `--plain` để in ra một khung hình, tiện cho script.

README chưa nêu một dòng kết quả cố định cho lệnh `init`, nên mình không đưa mẫu. Cách chắc nhất là chạy câu giao việc ở phần trên và xem Claude có làm theo hướng swarm hay không.

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

Bám theo những gì README mô tả, đây là vài tình huống.

### Lập trình viên muốn review nhanh một repo lạ

Bạn vừa nhận một dự án cũ, không biết đâu là chỗ dễ hỏng. Sau khi `init` và mở lại Claude Code, bạn gõ đúng 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: Claude tìm module rủi ro nhất, viết test cho nó và tóm tắt phần đã thay đổi. Hãy đọc kỹ phần test được sinh ra trước khi tin, vì README không hứa kết quả luôn đúng.

> Bạn vẫn viết code như cũ. Ruflo lo phần điều phối ở phía sau.
>
> — Ông T

### Người quản lý muốn nhìn thấy AI đang làm gì

Bạn không muốn mở log lằng nhằng. Cài `ruflo-console` rồi gõ `/ruflo`. Bảng điều khiển cho bạn theo dõi workflow, agent, model, token và chi phí cạnh Claude Code. Khi có việc lỗi, bạn mở log từng lần chạy, tìm kiếm và so sánh. Phù hợp khi bạn cần biết tiền token đi đâu.

### Thử cho Claude điều khiển console, có giới hạn

README có hẳn một bài tập an toàn:

1. Mở `/ruflo`, vào **Settings → Claude control**, chọn **write + ask**.
2. Gõ: 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 đang chờ trong console.
4. Kiểm tra mục Missions có mục tiêu đó và Overview ghi lại hành động.
5. Muốn dừng, bấm **Take back control**.

Lưu ý trong README: tạo mission không có nghĩa là tính năng đã được làm. Đây chỉ là cách tập kiểm soát AI một cách an toàn.

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

Nếu bạn không dùng Claude Code, trỏ client MCP vào `npx -y ruflo@latest mcp start`. Khi đó công cụ của Ruflo (bộ nhớ, swarm…) có thể gọi được từ client của bạn. Mức độ hỗ trợ từng client cụ thể mình chưa có thông tin ngoài README, nên hãy thử trên một dự án nhỏ trước.

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

**Claude Code không nhận agent sau khi init.** Nguyên nhân thường là bạn chưa khởi động lại. README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy đóng hẳn và mở lại trong đúng thư mục đã chạy `init`.

**Lệnh `/plugin` hoặc `claude plugin install` không chạy.** Rất có thể Claude Code của bạn cũ. Đường plugin cần 2.1.287 trở lên, lệnh từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi thử lại.

**`npx` báo lỗi phiên bản hoặc cú pháp.** package.json yêu cầu Node từ 20.0.0. Kiểm tra bằng `node --version`, nếu thấp hơn thì nâng cấp Node.

**Gọi nhầm tên công cụ MCP.** README lưu ý: plugin `ruflo-core` đăng ký công cụ với tên dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, khác tên ngắn như `memory_store` của đường CLI. Nếu bạn làm theo hướng dẫn của đường CLI mà đang dùng plugin, hãy đổi tên cho đúng, hoặc chuyển sang cài đầy đủ bằng `init`.

**Plugin chạy hai lần.** Với các plugin ngoài như `agentdb`, `agentic-flow`, `agentic-qe-fleet`, README dặn chỉ cài từ một marketplace. Nếu bật từ cả hai, mod và lệnh sẽ nạp hai lần.

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

**Điểm mạnh.** Vào cuộc rất nhanh bằng một lệnh. Giấy phép MIT. Có console để quan sát, có cơ chế phân quyền cho Claude (mặc định read + ask) và dự án vẫn đang được cập nhật. Phạm vi rộng: nhóm agent, bộ nhớ, plugin, kết nối nhiều máy (federation).

**Giới hạn.** README rất dài, với hàng trăm công cụ MCP và hàng chục lệnh, nên người mới dễ choáng. Tác giả cũng nói bạn không cần học hết, chỉ cần dùng Claude Code như thường. Một số phần được README tự ghi chú là mang tính khái niệm (vòng học, sơ đồ kiến trúc). Các đoạn demo dùng dữ liệu mẫu, không phải bằng chứng cho kết quả swarm hoàn chỉnh. Mod không có sandbox. Thông tin về hệ điều hành, chi phí API và yêu cầu phần cứng chưa rõ trong tư liệu mình có.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code hỏi đáp và sửa vài file, bản thân Claude Code là đủ, thêm Ruflo chỉ làm phức tạp hơn. Nếu bạn không muốn thêm file vào dự án, hãy dùng đường plugin. Nếu bạn cần cam kết bảo mật nghiêm ngặt, hãy đọc SECURITY.md trong repo và thử trên dự án nhỏ trước khi dùng cho dữ liệu thật.

Lời khuyên của mình: cài trên một dự án thử, giao đúng một tác vụ mẫu, xem console, rồi mới mở rộng dần.

## 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 bạn dùng tự do. Tuy nhiên Ruflo chạy trên Claude Code, Codex hoặc nhà cung cấp mô hình khác, và chi phí token của các bên đó là việc riêng. Tư liệu có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

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

Theo README, Claude Flow là tên cũ, nay dự án đã đổi thành Ruflo. Tên gói npm trong tư liệu vẫn ghi là claude-flow, còn lệnh trong README dùng npx ruflo. Cả hai thuộc cùng một dự án do Reuven Cohen (rUv) tạo ra.

### 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ó chạy được với Codex hoặc công cụ không phải Claude Code không?

Có. README nói Codex và các client MCP khác dùng được: đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. README cũng có tuỳ chọn riêng cho Grok Build bằng npx ruflo init --grok.

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

Có, nếu dùng npx ruflo init: dự án sẽ có thêm .claude/, .claude-flow/, CLAUDE.md, file helper và settings. Nếu muốn không thêm file nào, README gợi ý dùng đường plugin Claude Code. Riêng với Grok, thêm --dry-run để xem trước.

### Claude có thể tự làm mọi thứ trong Ruflo không, có an toàn không?

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

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

Tư liệu mình có chưa nêu yêu cầu GPU hay danh sách hệ điều hành được hỗ trợ. Bạn nên xem thêm tài liệu trong repo hoặc thử trên một dự án nhỏ trước.
