# Ruflo: điều phối nhóm 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: lớp công cụ bao quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ và hook. Bạn chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án rồi mở lại Claude Code. Cài đặt không khó nếu máy đã có Node 20 trở lên và Claude Code.

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

Ruflo là một “agent harness”: lớp công cụ đặt quanh Claude Code hoặc Codex để mô hình AI không chỉ trả lời, mà còn có agent chuyên biệt, bộ nhớ, vòng lặp và các giới hạn kiểm soát. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, viết chủ yếu bằng TypeScript, giấy phép MIT. Hiện có khoảng 81.582 sao và 9.607 fork trên GitHub.

Tác giả dùng một công thức dễ nhớ: Agent = Model + Harness. Mô hình lo việc viết. Harness lo phần còn lại: đưa công cụ, giữ ngữ cảnh giữa các bước, nhớ qua nhiều phiên làm việc, và giúp kiểm tra kết quả. Ruflo là phần harness đó.

Ai nên dùng? Lập trình viên đã quen Claude Code và muốn giao việc lớn cho nhiều agent phối hợp. Người mới cũng thử được, vì README nói rõ bạn không cần học hết hàng trăm công cụ bên trong. Sau khi chạy `init`, bạn cứ dùng Claude Code bình thường, còn hệ thống hook sẽ tự định tuyến tác vụ ở phía sau. Điểm đáng giá nhất là cài chỉ bằng một lệnh, và có bảng điều khiển (console) để bạn nhìn thấy agent đang làm gì.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là lớp điều phối bọc quanh Claude Code và Codex: thêm agent chuyên biệt, 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ì

Dưới đây là những tính năng chính, giải thích theo lợi ích thực tế.

**Nhóm agent phối hợp (swarm).** Thay vì một agent làm tất cả, Ruflo cho nhiều agent tự phân vai và cùng xử lý một việc. README nói cách cài đầy đủ mang theo 98 agent, hơn 60 lệnh và 30 skill. Lợi ích: bạn có thể giao một việc lớn như “review cả repo” thay vì chia nhỏ từng file.

**Bộ nhớ và học từ kinh nghiệm.** Ruflo lưu lại những gì đã làm để lần sau dùng lại, kể cả qua các phiên khác nhau. Bộ nhớ này nền tảng là cơ sở dữ liệu vector. README lưu ý: phần 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.

**Hook tự động.** Sau `init`, các hook tự định tuyến tác vụ và ghi nhận mẫu làm việc thành công. Bạn không phải gọi thủ công từng công cụ.

**MCP server.** Ruflo có MCP server, nên Codex hay bất kỳ MCP client nào khác cũng gọi được các công cụ của nó.

**Console (bảng điều khiển) trong Claude Code.** Gõ `/ruflo` để xem workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Bạn mở được log và kết quả của từng agent, tìm kiếm, xem lại và so sánh các lần chạy.

**Cho Claude điều khiển console, nhưng bạn đặt giới hạn.** Trong Settings → 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. Hành động vượt mức quyền sẽ bị từ chối, và các hành động liên quan mạng, chi tiêu hay phá huỷ vẫn phải xác nhận kể cả khi để `auto`.

**Hệ thống plugin.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học tập, kiểm thử, bảo mật, DevOps… 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 chi phí, `ruflo-aidefence` chặn prompt injection và phát hiện dữ liệu cá nhân.

**Liên kết nhiều máy (federation).** Agent trên các máy khác nhau có thể trao đổi an toàn, theo README là không làm lộ dữ liệu.

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

Tư liệu chỉ nêu rõ những điều sau:

- **Node.js từ 20.0.0 trở lên** (theo `package.json`). Bạn cần có `npx` đi kèm Node.
- **Claude Code** nếu muốn dùng đường cài chính. Riêng đường cài chỉ bằng plugin yêu cầu Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` ngoài terminal cần **2.1.292 trở lên**.
- Nếu dùng Codex hoặc client MCP khác: client đó phải cho cấu hình một MCP server bằng lệnh và tham số.
- Một thư mục dự án để chạy `init`.

Tư liệu không nói rõ về hệ điều hành hay yêu cầu phần cứng như GPU, nên mình không khẳng định gì ở hai điểm này. Về tài khoản và khoá API: README không nêu rõ cần loại nào cho việc cài Ruflo; bạn vẫn cần quyền dùng Claude Code hoặc Codex như bình thường để agent chạy được.

```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 cô lập (sandbox). README khuyên đọc code của mod trước khi cài. Hãy giữ Claude control ở mức mặc định read + ask, chỉ nâng quyền khi bạn thật sự cần.
```

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

README có ba đường cài. Đường nhanh nhất là chạy `init` trong dự án.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án của bạn
- Chạy init | Thêm agent, hook, 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 kế tiếp
- Giao một việc thật | Dán câu lệnh mẫu để thử swarm
- Mở console | Gõ /ruflo để xem bảng điều khiển
```

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

Mở terminal (PowerShell, Terminal hay cmd đều được) rồi chuyển vào thư mục dự án của bạn. Chỗ người mới hay vấp: chạy lệnh sai thư mục thì Ruflo sẽ thêm file vào nhầm chỗ. Hãy chắc mình đang đứng đúng trong thư mục dự án.

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

### Chạy lệnh init

Lệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo README, nó tạo các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings trong thư mục làm việc.

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

Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh riêng:

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

### Mở lại Claude Code trong cùng thư mục

Claude Code sẽ nhận agent, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code thì hãy thoát rồi mở lại trong chính thư mục dự án.

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

Dán câu mẫu này 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.
```

Câu này nhờ Ruflo dùng một swarm để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi.

### Mở console

Trong Claude Code, gõ lệnh sau để mở bảng điều khiển. Lưu ý: console là một plugin riêng, nên nếu gõ mà chưa thấy gì, hãy xem phần cài bằng plugin bên dưới.

```text
/ruflo
```

### Cách khác: chỉ cài plugin (không thêm file vào dự án)

Đường này cài công cụ lõi, console và các mod mà không thêm file nào vào dự án. Bạn gõ các lệnh sau bên trong Claude Code (cần bả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, trên Claude Code 2.1.292 trở lên, README có lệnh này:

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

So sánh nhanh theo README: đường plugin nhẹ hơn, chỉ có lệnh slash, vài skill và định nghĩa agent, không có hook. Đường `npx ruflo init` mới là bản đầy đủ, README khuyên dùng cho việc nghiêm túc.

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

Bạn cấu hình **command** là `npx` và **arguments** như sau:

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

Nghĩa là client sẽ chạy `npx -y ruflo@latest mcp start` để khởi động MCP server của Ruflo. Chỗ nhập cấu hình khác nhau tuỳ từng client, bạn xem tài liệu client đó.

### Cách khác: chạy console trong terminal thường

Console cũng chạy riêng, không cần Claude Code:

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

Theo tư liệu, có vài dấu hiệu để bạn tự kiểm tra:

- Sau `init` và khi mở lại Claude Code, dự án có thêm các thư mục như `.claude/` và `.claude-flow/` cùng file `CLAUDE.md`.
- Gõ `/ruflo` trong Claude Code thì mở được console.
- Với đường plugin: gõ `/plugin` và kiểm tra các mod xuất hiện trong dòng “active mods”.
- Nếu chạy `npx ruflo tui` thì khung bảng điều khiển hiện ngay trong terminal.

README không đưa ra một dòng chữ “thành công” cố định cho lệnh `init`, nên mình không bịa ra. Cách chắc nhất là thấy file mới trong dự án và mở được `/ruflo`.

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

### Dev nhận một repo lạ và cần biết chỗ nào rủi ro

Bạn vừa nhận bảo trì một dự án cũ, ít test. Sau khi chạy `init` và mở lại Claude Code, bạn dán 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ả bạn mong đợi: agent chỉ ra module rủi ro nhất, viết test cho module đó và báo lại những gì đã thay đổi. Hãy tự đọc và chạy lại các test đó trước khi tin, vì agent có thể viết sai.

> Agent = Model + Harness: mô hình viết, còn harness giúp nó thật sự làm việc được.
>
> — Ông T

### Người mới muốn nhìn tận mắt agent đang làm gì

Bạn không muốn agent chạy “trong bóng tối”. Hãy mở console bằng `/ruflo`. Theo README, bạn xem được workflow, agent, mô hình, token và chi phí. Bạn còn mở được log và kết quả từng agent để xem agent nào lỗi.

Nếu muốn thử cho Claude tự thao tác console, README có kịch bản an toàn: vào Settings → Claude control → chọn write + ask, rồi nhờ Claude:

```text
Create a mission to add a dark mode toggle. Show me the mission and its status.
```

Claude mở trang Missions và đặt mục tiêu; bạn xác nhận hành động tạo trong console. Sau đó kiểm tra mục Missions có mục tiêu mới và Overview ghi lại hành động. Lưu ý quan trọng của README: tạo “mission” không có nghĩa là tính năng dark mode đã được làm xong. Muốn dừng, bấm **Take back control**.

### Chủ dự án muốn thêm test và theo dõi chi phí

Nếu bạn chỉ cần vài chức năng, hãy cài đúng plugin thay vì cả bộ. Ví dụ `ruflo-testgen` (tìm test còn thiếu và sinh test) và `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí). Cú pháp cài theo mẫu README, bạn thêm marketplace trước:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo
```

README chỉ ghi lệnh cho `ruflo-core`, `ruflo-swarm`, `ruflo-rag-memory` và `ruflo-neural-trader`; các plugin khác bạn cài theo cùng kiểu `/plugin install <tên>@ruflo`, và nên mở `/plugin` hoặc `/ruflo market` để xem danh mục và nút cài. Kết quả: bạn có thêm lệnh slash và định nghĩa agent tương ứng, mà không có file nào bị thêm vào dự án.

### Người dùng Codex muốn dùng chung công cụ

Bạn không dùng Claude Code mà dùng Codex. Hãy trỏ Codex tới MCP server của Ruflo bằng command `npx` và các tham số `-y`, `ruflo@latest`, `mcp`, `start` như ở phần cài đặt. Từ đó các công cụ của Ruflo hiện ra như công cụ MCP bình thường trong Codex. Muốn thiết lập theo từng bước hỏi đáp, chạy `npx ruflo@latest init wizard`.

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

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

**Mở Claude Code nhưng 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 Claude Code, rồi mở lại trong đúng thư mục đã chạy `init`. Với cài bằng plugin, thử `/reload-plugins`.

**Lệnh `/plugin` hoặc `claude plugin install` không nhận.** Đường plugin cần Claude Code từ 2.1.287, còn lệnh ngoài terminal cần 2.1.292. Hãy cập nhật Claude Code trước.

**Plugin ngoài bị nạp hai lần.** 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 marketplace (hoặc marketplace riêng của chúng, hoặc `ruflo`), không cài từ cả hai, nếu không mod và lệnh sẽ nạp hai lần.

**Claude từ chối thao tác trong console.** Đó là cơ chế bảo vệ. Hành động vượt quá mức quyền bạn đặt (read, write, manage, full) sẽ bị từ chối, và một số hành động như tiêu tiền hay phá huỷ luôn cần xác nhận. Nếu đúng ý bạn, hãy nâng mức quyền một cách có chủ ý; nếu thấy Claude làm quá tay, bấm **Take back control**.

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

**Điểm mạnh.** Cài đặt chỉ một lệnh. Có đường cài nhẹ không thêm file vào dự án. Bạn kiểm soát được mức quyền khi cho Claude điều khiển console. Hệ sinh thái rộng (agent, bộ nhớ, bảo mật, theo dõi chi phí), hoạt động cả với Claude Code lẫn Codex. Giấy phép MIT và repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Dự án rất lớn: README nhắc tới hàng trăm công cụ MCP và hàng chục lệnh CLI, nên người mới dễ choáng nếu muốn hiểu hết. README cũng tự nói rõ một số video demo dùng dữ liệu mẫu hoặc replay khung hình, chúng không chứng minh swarm đã hoàn thành việc thật hay bộ nhớ đã nhớ lại đúng. Các mod chạy bằng quyền tài khoản và không được sandbox. Tư liệu chưa cho biết chi phí token thực tế cho một swarm, nên bạn cần tự theo dõi.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần một trợ lý viết code đơn giản, dùng Claude Code hay Codex thuần là đủ, chưa cần thêm một lớp điều phối. Hãy thử Ruflo khi việc của bạn đủ lớn để cần nhiều agent, cần bộ nhớ giữa các phiên, hoặc cần nhìn rõ agent đang làm gì. Khuyến nghị của mình: thử trên một dự án nhỏ trước, giữ quyền ở mức read + ask, rồi mới mở rộng.

## 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 không nói gì về giá của Claude Code, Codex hay các nhà cung cấp mô hình mà agent gọi tới, nên chi phí đó bạn cần tự kiểm tra. Có plugin ruflo-cost-tracker để theo dõi token và cảnh báo chi phí.

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

Theo README, Claude Flow chính là tên cũ: dự án nay đã đổi tên thành Ruflo, do rUv đặt. Gói npm hiện vẫn có tên claude-flow, còn lệnh khuyến nghị là npx ruflo@latest.

### Cần cài gì trước khi dùng?

Cần Node.js từ phiên bản 20.0.0 trở lên. Nếu dùng đường plugin thì cần Claude Code 2.1.287 trở lên. Tư liệu chưa nêu yêu cầu phần cứng như GPU.

### Dùng được với Codex hay chỉ với Claude Code?

Dùng được cả hai. Với Codex hoặc client MCP khác, bạn cấu hình command là npx và các tham số -y, ruflo@latest, mcp, start. README cũng nhắc tới tích hợp với Grok qua lệnh npx ruflo init --grok.

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

Nếu chạy npx ruflo init thì có: README nói nó thêm .claude/, .claude-flow/, CLAUDE.md, file hỗ trợ và settings vào thư mục làm việc. Nếu không muốn thêm file nào, hãy dùng đường cài bằng plugin, theo README là không thêm file vào dự án.

### Claude có tự ý làm bậy trong console không?

Mặc định chỉ ở mức read và phải hỏi bạn trước (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 hay phá huỷ luôn cần xác nhận kể cả khi để auto. Bạn có thể bấm Take back control để dừng.

### Có cần học hết các công cụ và lệnh của Ruflo không?

Không. README nói bạn không cần học hết hàng trăm công cụ MCP hay các lệnh CLI. Sau khi chạy init, bạn dùng Claude Code như bình thường và hệ thống hook sẽ tự định tuyến tác vụ, học từ mẫu thành công và phối hợp agent ở phía sau.
