# 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: lớp công cụ bọc quanh Claude Code và Codex để thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên và MCP server. Bạn dùng nó để Claude Code làm việc có tổ chức hơn trên dự án thật. Cài khá dễ: chạy một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên.

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

Ruflo là một «agent harness», tức bộ khung chạy quanh Claude Code và Codex. Nó thêm cho các công cụ AI viết code đó một đội agent chuyên biệt, bộ nhớ giữ qua nhiều phiên làm việc, hook tự động và một MCP server. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, giấy phép MIT, viết chủ yếu bằng TypeScript.

Vấn đề nó giải quyết khá quen thuộc. Khi bạn giao một việc lớn cho Claude Code, mỗi phiên làm việc thường bắt đầu từ con số không, và một agent phải ôm hết mọi thứ. Ruflo chia việc cho nhiều agent, nhớ lại những gì đã làm tốt và giúp bạn theo dõi chúng trong một màn hình điều khiển. Tác giả tóm gọn bằng công thức: Agent = Model + Harness. Model viết code, còn harness cấp công cụ, bộ nhớ, vòng lặp và giới hạn để model làm việc được.

Bạn nên đọc bài này nếu đã biết dùng Claude Code hoặc Codex ở mức cơ bản và muốn làm việc có hệ thống hơn: lập trình viên mới, người làm kỹ thuật trong doanh nghiệp, hoặc người thích thử nghiệm AI. Repo hiện có khoảng 81.600 sao và khoảng 9.600 fork, vẫn được cập nhật trong vài tháng gần đây. Điểm đáng giá nhất là cách cài: chỉ một lệnh, sau đó bạn cứ dùng Claude Code như bình thường.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung chạy quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ, hook và MCP server, cài bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Tư liệu của repo khá dài và nhiều tính năng. Dưới đây là những phần dễ hiểu và hữu ích nhất với người mới.

**Đội agent chuyên biệt và swarm.** Ruflo cung cấp hàng trăm agent theo vai trò (README ghi «100+ specialized agents», bảng so sánh cài đặt ghi 98 agent). Chúng có thể tự tổ chức thành «swarm», nghĩa là một nhóm agent cùng xử lý một nhiệm vụ. Lợi ích thực tế: bạn nhờ một câu như «review repo này, tìm module rủi ro nhất, viết test», thay vì tự chia việc từng bước.

**Hook tự động.** Sau khi cài, hook tự chuyển nhiệm vụ cho đúng agent, học từ các lần làm thành công và điều phối ngầm phía sau. README nói rõ bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Cứ dùng Claude Code như thường.

**Bộ nhớ qua các phiên.** Ruflo có bộ nhớ vector để agent nhớ lại kinh nghiệm cũ. Lợi ích: bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở phiên mới. README có lưu ý rằng phần học cục bộ vẫn cần embedding và các module học được cấu hình sẵn, nên đừng hiểu nó là phép màu.

**Màn hình điều khiển (console).** Đây là «buồng lái» đặt cạnh Claude Code, để theo dõi workflow, agent, model, token và chi phí. Bạn mở log của từng agent, tìm kiếm, xem lại và so sánh các lần chạy. Mở bằng lệnh `/ruflo` trong Claude Code, hoặc chạy riêng trong terminal.

**Cho Claude điều khiển, bạn đặt giới hạn.** Trong Settings → Claude control, bạn chọn mức quyền `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 liên quan đến mạng, chi tiêu hoặc có tính phá huỷ vẫn phải xác nhận kể cả khi đang ở `auto`.

**Hệ plugin.** Repo có 48 plugin (cộng thêm 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử code, bảo mật, DevOps. 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.

**Liên kết nhiều máy (federation).** Agent trên các máy khác nhau có thể trao đổi với nhau một cách an toàn. Tính năng này dành cho nhu cầu nâng cao, người mới chưa cần.

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

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

- **Node.js 20.0.0 trở lên.** Đây là yêu cầu `engines` trong package.json. Lệnh `npx` đi kèm Node.
- **Claude Code** (hoặc Codex / một MCP client khác). Ruflo là lớp bọc quanh chúng nên bạn phải có sẵn một công cụ như vậy.
- **Claude Code phiên bản 2.1.287 trở lên** nếu bạn chọn đường cài plugin. Riêng lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên.
- **Một thư mục dự án** để chạy lệnh `init`.

Về hệ điều hành, tài khoản, API key hay phần cứng (GPU), phần README mình có không nói rõ yêu cầu nào khác. Nếu bạn dùng Claude Code thì tài khoản và quyền truy cập của Claude Code là việc riêng của công cụ đó. Muốn chắc hơn, bạn xem thêm README.md và thư mục docs trong 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 code trước khi cài. Với plugin và mod nói chung, hãy chỉ cài những gì bạn thật sự cần.
```

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

Ruflo có nhiều đường cài. Đường nhanh nhất và đầy đủ nhất là lệnh `init`. Mình tóm tắt như sau:

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

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

Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. Ruflo ghi file vào dự án hiện tại, nên bạn phải đứng trong thư mục dự án trước. Ví dụ trên Windows 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 tới thư mục của bạn.

### 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 mà không cần cài toàn cục. `init` sẽ thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh trong README, cách này tạo ra các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng một số file hỗ trợ và settings. Bạn nên commit dự án sạch trước khi chạy để dễ xem Ruflo đã thêm gì.

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

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

### Mở lại Claude Code

Sau `init`, hãy mở Claude Code trong 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 kế tiếp. Nếu Claude Code đang mở sẵn, hãy đóng rồi mở lại.

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

Dán câu lệnh 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.
```

Bạn có thể viết bằng tiếng Việt cho thuận tay, nhưng câu mẫu trên là câu gốc đã được tác giả thử.

### Cách khác: chỉ cài plugin cho Claude Code

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

Đường này chỉ cho một phần chức năng. README nêu rõ: plugin cho bạn lệnh slash, vài skill và định nghĩa agent, còn bản đầy đủ (98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon) nằm ở đường `npx ruflo init`. Nếu mục tiêu là dùng thật, hãy chọn `init`.

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

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

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

Với Codex hoặc công cụ hỗ trợ MCP, bạn cấu hình **command** là `npx` và **arguments** là danh sách sau:

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

Tương đương câu lệnh `npx -y ruflo@latest mcp start`. Mỗi công cụ có chỗ điền cấu hình MCP khác nhau, README không chỉ rõ từng chỗ, nên bạn xem tài liệu của công cụ mình dùng.

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

Console chạy được độc lập, 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 README, có vài dấu hiệu để biết cài thành công:

1. **Lệnh `npx ruflo@latest init` chạy xong không báo lỗi**, và trong thư mục dự án xuất hiện `.claude/`, `.claude-flow/` và `CLAUDE.md`.
2. **Mở lại Claude Code rồi gõ `/ruflo`.** Màn hình điều khiển hiện ra là dấu hiệu rõ nhất.
3. **Với đường plugin**, gõ `/plugin` để xem các plugin có nằm trong dòng «active mods» hay không.
4. **Thử một việc thật** bằng câu lệnh swarm ở phần trên. Claude Code nên bắt đầu điều phối các agent thay vì chỉ trả lời một lần.
5. **Thử bài kiểm tra an toàn của README:** bật Settings → Claude control ở mức write + ask, rồi yêu cầu: «Create a mission to add a dark mode toggle. Show me the mission and its status.» Bạn sẽ thấy một yêu cầu tạo mission chờ bạn xác nhận. Sau khi xác nhận, mission xuất hiện trong trang Missions và hành động được ghi lại ở Overview. Lưu ý README nói tạo mission không có nghĩa là tính năng đã được code xong.

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

Các tình huống dưới đây bám theo khả năng có trong tư liệu. Kết quả cụ thể phụ thuộc dự án và model bạn dùng.

### Lập trình viên mới: nhờ review một repo lạ

Bạn vừa nhận một dự án cũ của công ty và không biết bắt đầu từ đâu. Sau khi cài `init` và mở Claude Code, bạn gõ:

```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 chia việc cho các agent, chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt các thay đổi. Bạn xem lại bản tóm tắt rồi duyệt diff như bình thường. Đừng gộp thay đổi khi chưa đọc.

> Cứ dùng Claude Code như bình thường, phần điều phối để Ruflo lo ngầm phía sau.
>
> — Ông T

### Người phụ trách kỹ thuật: theo dõi agent đang làm gì và tốn bao nhiêu

Trưởng nhóm muốn biết AI đang chạy việc gì và tốn bao nhiêu token. Bạn cài `ruflo-console` rồi gõ `/ruflo`. Console cho thấy workflow, agent, model, token và chi phí. Khi một agent làm sai, bạn mở log và kết quả của nó để xem lại, tìm kiếm và so sánh với lần chạy khác. README cũng có plugin `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí.

### Dev làm việc nhiều ngày: giữ bối cảnh qua các phiên

Bạn đang sửa một hệ thống lớn trong nhiều ngày. Phần bộ nhớ của Ruflo (vector memory, và plugin như `ruflo-rvf` để lưu và khôi phục bộ nhớ agent giữa các phiên) giúp agent nhớ lại kinh nghiệm cũ. Bạn đỡ phải giải thích lại cấu trúc dự án mỗi sáng. Nhớ rằng README ghi rõ phần học vẫn cần embedding và module học được cấu hình, nên hãy kiểm tra kết quả thay vì tin hoàn toàn.

### Người thử nghiệm: cho Claude điều khiển console trong giới hạn an toàn

Bạn muốn thử cho Claude thao tác trên console nhưng sợ nó làm bậy. Vào Settings → Claude control, chọn mức `write` với chế độ `ask`. Khi Claude tạo mission hay đổi trạng thái, bạn là người bấm xác nhận. Nếu thấy không ổn, bấm **Take back control** để dừng ngay các công cụ console của Claude. README cho biết hành động vượt quá mức quyền bạn đặt sẽ bị từ chối.

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

**Lệnh `npx` báo không tìm thấy hoặc lỗi phiên bản.** Máy bạn có thể chưa cài Node, hoặc Node cũ hơn 20. Gõ `node --version` để kiểm tra, và nâng lên Node 20 trở lên nếu cần.

**Cài xong nhưng Claude Code không thấy agent hay lệnh `/ruflo`.** Thường là do Claude Code chưa được khởi động lại, hoặc bạn mở nó ở thư mục khác với thư mục đã chạy `init`. Hãy đóng hẳn Claude Code, mở lại đúng thư mục dự án. Với đường plugin, chạy `/reload-plugins`.

**Lệnh `/plugin install` báo lỗi hoặc không có.** Đường plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 trở lên với lệnh `claude plugin install` ngoài terminal). Hãy cập nhật Claude Code trước.

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

**Dự án bị thêm nhiều file lạ.** Đó là việc bình thường của `init` (như `.claude/`, `.claude-flow/`, `CLAUDE.md`). Hãy chạy thử trên một nhánh riêng hoặc dự án nhỏ trước. Nếu không muốn thêm file nào, dùng đường plugin, vì README ghi đường này không thêm file vào dự án.

**Nhầm giữa tên công cụ MCP của hai đường cài.** Plugin `ruflo-core` đặt tên công cụ theo dạng `mcp__plugin_ruflo-core_ruflo__*`, khác tên `memory_store`, `swarm_init`, `agent_spawn` của đường CLI. Nếu một hướng dẫn dùng tên khác với máy bạn, hãy xem bạn đang theo đường nào.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Giấy phép MIT. Dự án lớn, có cộng đồng và còn được cập nhật. Có console theo dõi chi phí, log và agent. Cơ chế quyền `read` / `write` / `manage` / `full` cùng chế độ `ask` khá rõ ràng. Có nhiều đường cài để bạn chọn mức cam kết.

**Giới hạn.** Repo rất lớn: 48 plugin, hàng trăm công cụ, nhiều khái niệm như swarm, federation, vector memory. Người mới dễ choáng, nên hãy bắt đầu với `init` và một việc nhỏ. Tác giả cũng thừa nhận phần học là «conceptual learning loop» (vòng lặp học ở mức khái niệm), và các bản demo trong README dùng dữ liệu mẫu hoặc không chứng minh việc swarm hoàn thành công việc thật. Hãy đọc kết quả với tinh thần kiểm chứng. Cuối cùng, các mod chạy với quyền tài khoản của bạn nên cần thận trọng.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần Claude Code viết một đoạn code nhỏ, hoặc chỉ làm việc một mình trên một file, Ruflo là thừa. Nếu bạn không dùng Claude Code, Codex hay MCP client nào, nó cũng chưa có ích. Hãy dùng công cụ trơn trước, và khi thấy mình cần chia việc cho nhiều agent, nhớ ngữ cảnh lâu dài, hay theo dõi chi phí, lúc đó Ruflo mới đáng thử.

## Câu hỏi thường gặp

### Ruflo có miễn phí không?

Repo dùng giấy phép MIT, nghĩa là bạn được dùng và sửa mã nguồn. Tư liệu mình có không nói gì về phí của các dịch vụ đi kèm. Chi phí gọi model (ví dụ qua Claude Code) tính theo tài khoản của bạn, và Ruflo có plugin theo dõi token và ngân sách.

### Ruflo cài bằng cách nào, có khó không?

Cách chính là chạy `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Sau đó bạn mở lại Claude Code để nó nhận cấu hình. Với người đã quen dùng terminal thì khá đơn giản.

### Ruflo khác gì dùng Claude Code trơn?

Ruflo là lớp bọc quanh Claude Code và Codex. Nó thêm đội agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook tự động, MCP server và console theo dõi. Bạn vẫn dùng Claude Code như bình thường, còn việc điều phối chạy ngầm.

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

README nói Codex và các MCP client khác dùng được. Bạn cấu hình command là `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Mỗi công cụ có chỗ nhập cấu hình khác nhau nên bạn cần xem tài liệu của công cụ đó.

### Có cần GPU không, chạy Windows được không?

Phần tư liệu mình có không nêu yêu cầu GPU hay danh sách hệ điều hành hỗ trợ. Yêu cầu rõ ràng duy nhất là Node 20 trở lên. Bạn nên xem README và thư mục docs trong repo để biết chi tiết cho máy của mình.

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

Có, nếu dùng `init`: README ghi nó thêm `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và settings. Đường chỉ cài plugin thì không thêm file nào vào dự án. Bạn nên thử trên nhánh riêng hoặc dự án nhỏ trước.

### Cho Claude điều khiển console của Ruflo có an toàn không?

Bạn tự đặt mức quyền (`read`, `write`, `manage`, `full`) và chế độ duyệt (`ask` hoặc `auto`). Mặc định hiện là read + ask. Hành động liên quan đến mạng, chi tiêu hoặc có tính phá huỷ vẫn cần xác nhận kể cả khi ở `auto`, và bạn có thể bấm Take back control để dừng.
