# Ruflo: điều phối nhiều AI agent làm việc cùng Claude Code — 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ụ bọc quanh Claude Code và Codex để nhiều agent phối hợp, nhớ việc giữa các phiên và có bảng điều khiển theo dõi. Bạn chỉ cần chạy một lệnh `npx ruflo@latest init` trong thư mục dự án, nên cài khá dễ nếu đã có Node.js. Giấy phép MIT, miễn phí sử dụng.

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

Ruflo là một "agent harness": lớp công cụ đặt quanh Claude Code và Codex để AI không chỉ trả lời từng câu mà còn có đội agent, bộ nhớ và cơ chế điều phối. Nó do Reuven Cohen (rUv) làm ra, trước đây mang tên Claude Flow. Repo hiện có khoảng 81.588 sao và 9.608 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.

Vấn đề nó giải quyết khá quen thuộc. Dùng Claude Code cho việc lớn, bạn thường phải tự chia việc, tự nhắc lại bối cảnh ở mỗi phiên, và khó biết AI đang làm gì. Ruflo thêm phần "điều phối" cho việc đó: nhiều agent chia nhau làm, ghi nhớ kinh nghiệm, và có một bảng điều khiển để bạn theo dõi.

Người nên thử là lập trình viên (kể cả mới) đã dùng Claude Code hoặc Codex và muốn giao những việc nhiều bước như rà soát repo, viết test, ghi tài liệu. Điểm đáng giá nhất là cách cài: một lệnh `npx ruflo@latest init`, sau đó bạn cứ dùng Claude Code như bình thường. README nói rõ bạn không cần học hết hàng trăm công cụ và lệnh bên trong.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm đội agent, bộ nhớ lâu dài và bảng điều khiển, cài bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Ruflo có rất nhiều thứ. Dưới đây là những phần chính theo README, kèm lợi ích thực tế.

- **Đội agent và swarm.** README nói Ruflo thêm hơn 100 agent chuyên biệt và cho chúng phối hợp thành "swarm". Lợi ích: bạn giao một việc lớn, các agent tự chia nhau thay vì bạn phải chia thủ công.
- **Hooks tự định tuyến.** Sau khi chạy `init`, hệ thống hook tự chuyển việc cho đúng agent và học từ những lần thành công, chạy ngầm. Bạn không phải gọi từng công cụ.
- **Bộ nhớ qua nhiều phiên.** Có agentdb, rvf và các plugin truy xuất (RAG) để lưu và tìm lại kinh nghiệm. Lợi ích: bớt phải giải thích lại bối cảnh dự án mỗi lần mở phiên mới.
- **Bảng điều khiển `/ruflo`.** Theo dõi workflow, agent, model, token và chi phí ngay cạnh Claude Code, xem log từng lần chạy, tìm kiếm, phát lại và so sánh. Bạn có thể cho Claude điều khiển bảng này, nhưng mức quyền do bạn đặt (read, write, manage, full), mặc định là đọc và hỏi lại trước khi làm.
- **Hệ plugin.** Repo có hơn bốn chục plugin nhỏ: swarm, tạo test tự động (ruflo-testgen), theo dõi chi phí (ruflo-cost-tracker), quét bảo mật (ruflo-security-audit), chống prompt injection (ruflo-aidefence)... Bạn cài cái nào cần, không bắt buộc cài hết.
- **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òn có giao diện terminal chạy độc lập.
- **Liên kết giữa nhiều máy (federation).** Agent trên các máy khác nhau có thể trao đổi với nhau. Đây là phần nâng cao, người mới có thể bỏ qua.

## 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.** Đây là yêu cầu trong package.json, và bạn cần nó để chạy lệnh `npx`.
- **Claude Code** nếu dùng đường cài chính. Nếu cài theo kiểu plugin trong Claude Code thì cần Claude Code từ 2.1.287 trở lên. Lệnh `claude plugin install` ở 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` trong đó.

Hệ điều hành, yêu cầu phần cứng (GPU, RAM) và API key riêng: phần README mình có chưa nói rõ. Phần README mình đọc cũng không nêu giá gói Claude hay chi phí gọi model. Bạn dùng tài khoản Claude Code hay Codex nào thì chi phí theo tài khoản đó.

```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 bạn đọc mã trước khi cài. Hãy nhớ điều này nhất là khi dùng trên máy có dữ liệu công ty.
```

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

```steps
- Mở terminal trong thư mục dự án | Dùng đúng thư mục bạn muốn AI làm việc
- Chạy lệnh init | npx ruflo@latest init để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude Code | Mở Claude Code ở cùng thư mục để nó nhận cấu hình mới
- Giao một việc thật | Dùng câu lệnh mẫu của README để thử
- (Tuỳ chọn) Mở bảng điều khiển | Gõ /ruflo trong Claude Code
```

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

Đây là chỗ người mới hay vấp nhất. Lệnh `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, bạn có thể tạo thư mục thử. Ví dụ trên Windows PowerShell hoặc macOS/Linux:

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

Hãy thay `duong-dan-toi-du-an-cua-ban` bằng đường dẫn thật. Đừng chạy ở thư mục chứa nhiều dự án khác nhau.

### Chạy lệnh init

Đây là lệnh chính theo 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. Phần so sánh trong README nói đường này tạo thêm các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` trong dự án của bạn. Vì vậy nếu dự án đang dùng git, bạn nên commit trước để dễ xem hoặc hoàn tác phần Ruflo thêm vào.

Muốn cấu hình từng bước theo kiểu hỏi đáp, README có lệnh:

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

Nếu chỉ muốn xem trước Ruflo sẽ ghi gì (README nêu cờ này trong phần Grok Build), thêm `--dry-run`. README chỉ ghi cờ này cho lệnh `init --grok`, nên với `init` thường mình chưa chắc, bạn thử và đọc kết quả.

### Mở lại Claude Code

Mở Claude Code ở cùng thư mục. README nói 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 một phiên Claude Code, hãy thoát và mở lại.

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

Gõ câu mẫu của README 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 bảo Claude dùng swarm của Ruflo để rà repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn có thể viết bằng tiếng Việt, nhưng mình chỉ dẫn lại câu tiếng Anh vì đó là câu README đã dùng.

### Cách khác: cài dạng plugin trong Claude Code

Nếu không muốn thêm file vào dự án, README có đường "chỉ plugin" (cần Claude Code 2.1.287 trở lên). Gõ lần lượt 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
```

Đường này không thêm file nào vào dự án. Đổi lại, README nói nó chỉ cho lệnh gạch chéo và một số kỹ năng, agent. Bản đầy đủ gồm hook và daemon chỉ có khi cài bằng `npx ruflo@latest init`. Muốn cài từ terminal (Claude Code 2.1.292 trở lên):

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

### Cách khác: dùng với Codex hoặc client MCP khác

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

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

Chỗ nhập cấu hình khác nhau tuỳ client, nên bạn xem tài liệu của client đó.

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

README không đưa ra một lệnh "kiểm tra phiên bản" riêng, nên mình gợi ý các dấu hiệu theo tư liệu:

1. Lệnh `npx ruflo@latest init` chạy xong, không báo lỗi, và trong dự án xuất hiện các mục mà README nhắc: `.claude/`, `.claude-flow/`, `CLAUDE.md`.
2. Mở lại Claude Code, gõ `/ruflo`. Nếu bảng điều khiển hiện ra là đã nhận. Với cách cài plugin, README bảo mở `/plugin` và xem plugin có trong dòng "active mods".
3. Thử câu mẫu ở trên. Nếu Claude bắt đầu chia việc và tạo test thì Ruflo đang hoạt động.
4. Muốn thử nhanh ngoài Claude Code, chạy giao diện terminal:

```bash
npx ruflo tui
```

Thêm `--plain` để in một khung hình ra, hợp khi chạy trong script.

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

### Rà soát một repo và viết test cho chỗ yếu nhất

**Bối cảnh:** bạn là lập trình viên nhận lại một dự án cũ, ít test, không rõ chỗ nào dễ hỏng.

**Cách làm:** sau khi `init`, mở Claude Code trong thư mục dự án và giao đúng việc mà README gợi ý:

```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ả:** theo mô tả README, bạn nhận được module được đánh giá rủi ro nhất, các test mới và bản tóm tắt thay đổi. Hãy đọc kỹ test AI viết và tự chạy lại trước khi tin.

> Giao cho AI một việc có đầu có đuôi, rồi kiểm tra kết quả, hiệu quả hơn nhiều so với hỏi lẻ từng câu.
>
> — Ông T

### Cho Claude tạo "mission" trong bảng điều khiển

**Bối cảnh:** bạn muốn theo dõi việc AI làm, nhưng chưa muốn để nó tự ý làm nhiều thứ.

**Cách làm:** theo kịch bản trong README:

1. Cài console (`/plugin install ruflo-console@ruflo`), mở `/ruflo`, vào **Settings → Claude control** và chọn **write + ask**.
2. Nhờ Claude: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
3. Xác nhận thao tác tạo mission khi bảng điều khiển hỏi.
4. Kiểm tra mục Missions và Overview có ghi lại việc này.

**Kết quả:** một mission mới xuất hiện cùng nhật ký hành động. README lưu ý rõ: tạo mission không có nghĩa tính năng dark mode đã được làm xong. Nếu muốn dừng, bấm **Take back control** để thu lại quyền.

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

**Bối cảnh:** bạn không dùng Claude Code mà dùng Codex hoặc một client MCP khác và vẫn muốn có bộ nhớ, đội agent.

**Cách làm:** khai báo MCP server với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Nếu muốn cấu hình dự án theo từng bước hỏi đáp, chạy `npx ruflo@latest init wizard`.

**Kết quả:** client của bạn gọi được các công cụ MCP của Ruflo. Mình chưa có thông tin chi tiết về từng client cụ thể ngoài những gì README nêu.

### Xem giao diện theo dõi ngay trong terminal

**Bối cảnh:** bạn quản lý một nhóm nhỏ và chỉ muốn xem thử bảng điều khiển trước khi quyết định có dùng Ruflo không.

**Cách làm:** chạy `npx ruflo tui` trong terminal. README nói giao diện này chạy độc lập, không cần Claude Code.

**Kết quả:** bạn thấy bảng theo dõi workflow, agent, model, token và chi phí. Lưu ý animation trong README dùng dữ liệu mẫu, nên đừng coi đó là bằng chứng các agent đã làm xong việc thật.

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

**Báo thiếu `npx` hoặc `node` không nhận.** Bạn chưa cài Node.js hoặc phiên bản cũ hơn 20. Cài hoặc nâng Node.js lên bản 20 trở lên, đóng và mở lại terminal rồi chạy lại.

**Claude Code không thấy agent hay lệnh `/ruflo` sau khi init.** 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 và mở lại trong đúng thư mục đã chạy `init`. Với cách cài plugin, thử `/reload-plugins`.

**Lệnh `/plugin install` không chạy.** Có thể Claude Code của bạn cũ. Đường plugin cần bản 2.1.287 trở lên, còn lệnh `claude plugin install` ở terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước.

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

**Thư mục dự án bị thêm nhiều file lạ.** Đó là hành vi của `init` (`.claude/`, `.claude-flow/`, `CLAUDE.md`...). Nếu dùng git, bạn xem `git status` để biết đã thêm gì. Nếu không muốn thêm file nào, hãy dùng đường cài plugin thay vì `init`.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Bạn được cả một hệ sinh thái: đội agent, bộ nhớ, bảng điều khiển, plugin theo nhu cầu. Mã nguồn mở (MIT), repo vẫn được cập nhật trong những tháng gần đây. Cơ chế phân quyền cho bảng điều khiển (mặc định đọc và hỏi lại) cũng đáng yên tâm.

**Giới hạn.** Hệ thống rất lớn, README nhắc tới hàng trăm công cụ MCP và hàng chục lệnh, nên với người mới nó có thể hơi rối. Một số tư liệu trong repo cũng tự nói rõ phần nào chỉ là minh hoạ: sơ đồ học là "khái niệm", animation dùng dữ liệu mẫu. Phần tự học, bộ nhớ và swarm cần bạn tự kiểm chứng trên việc thật của mình. Mình chưa có số liệu đo hiệu quả hay chi phí thực tế.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code làm việc nhỏ lẻ, dùng thẳng Claude Code là đủ. Nếu không muốn có thêm file hay hook trong dự án, hãy thử đường plugin trước. Nếu máy chứa dữ liệu nhạy cảm, hãy đọc mã của mod và plugin trước khi cài, vì chúng chạy với quyền tài khoản của bạn.

Cách thử an toàn nhất: tạo một dự án nháp, chạy `npx ruflo@latest init`, giao đúng câu mẫu của README và quan sát. Hợp thì mới mang vào dự án thật.

## 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. Tuy nhiên Ruflo chạy cùng Claude Code, Codex hoặc các nhà cung cấp model khác, nên chi phí gọi model phụ thuộc vào tài khoản bạn đang dùng. Tư liệu mình có chưa nêu giá cụ thể.

### Cần cài những gì để chạy Ruflo?

package.json yêu cầu Node.js từ 20.0.0 trở lên. Bạn cũng cần Claude Code (hoặc Codex hay một client MCP). Nếu cài theo kiểu plugin, README yêu cầu Claude Code từ 2.1.287 trở lên.

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

README mình đọc không nói rõ về hệ điều hành. Lệnh cài là `npx ruflo@latest init` nên về nguyên tắc cần Node.js. Bạn nên thử trên một dự án nháp trước, và chưa có thông tin chính thức về mức hỗ trợ từng hệ điều hành.

### Có cần GPU không?

Tư liệu không yêu cầu GPU cho đường cài chính. Một vài plugin như ruflo-ruvector có nhắc tìm kiếm tăng tốc bằng GPU, nhưng README không nói đây là bắt buộc. Chưa có thông tin về yêu cầu phần cứng tối thiểu.

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

Claude Code là công cụ chính để viết code. Ruflo là lớp bọc quanh nó, thêm đội agent, swarm, bộ nhớ qua nhiều phiên, hook tự định tuyến và bảng điều khiển theo dõi. Bạn vẫn dùng Claude Code như bình thường, Ruflo chạy ngầm phối hợp.

### Cài Ruflo xong thì dự án của tôi bị thay đổi gì?

Với `npx ruflo@latest init`, README nói dự án sẽ có thêm `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và cài đặt. Đường cài chỉ plugin thì không thêm file nào vào dự án, nhưng chỉ có một phần tính năng.

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

README cho biết mặc định là read + ask, tức chỉ đọc và hỏi lại. Bạn tự nâng quyền lên write, manage hoặc full nếu muốn. Hành động liên quan mạng, chi tiêu và phá huỷ vẫn cần xác nhận kể cả ở chế độ auto, và có nút Take back control để thu lại quyền. Riêng các mod thì chạy với quyền tài khoản của bạn, nên cần đọc mã trước.
