# 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ụ bao quanh Claude Code và Codex để thêm agent chuyên biệt, bầy agent phối hợp, bộ nhớ qua nhiều phiên và máy chủ MCP. Bạn dùng nó để giao việc lớn cho nhiều agent cùng làm thay vì một cuộc chat đơn lẻ. Cài khá dễ vì chỉ cần Node 20 trở lên và một lệnh npx trong thư mục dự án.

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

ruflo là một bộ khung (harness) bao quanh Claude Code và Codex. Nó thêm vào dự án của bạn các agent chuyên biệt, hook tự động, bộ nhớ lưu giữa các phiên làm việc và một máy chủ MCP. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.600 sao và 9.600 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.

Tư liệu của tác giả giải thích bằng một công thức: Agent = Model + Harness. Mô hình AI chỉ viết ra chữ. Harness là phần "bàn làm việc" quanh nó: công cụ, bộ nhớ, vòng lặp, giới hạn an toàn để agent làm được việc thật. ruflo đóng vai phần bàn làm việc đó, để nhiều agent không chạy riêng lẻ mà phối hợp với nhau.

Bạn nên đọc bài này nếu đang dùng Claude Code hoặc Codex và muốn giao những việc dài hơi hơn: rà soát cả một repo, viết bộ test, theo dõi tiến độ nhiều tác vụ. Điểm đáng giá nhất là cách cài rất ngắn: một lệnh `npx ruflo@latest init`, sau đó bạn vẫn dùng Claude Code như bình thường. Phần điều phối chạy nền.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung điều phối giúp Claude Code và Codex chạy nhiều agent phối hợp, có bộ nhớ lâu dài, hook tự động và máy chủ MCP, cài bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Tư liệu nhắc đến nhiều con số (hàng trăm công cụ MCP, hàng chục lệnh CLI). Bạn không cần học hết. Dưới đây là những thứ có ích nhất với người mới.

- **Nhiều agent chuyên biệt làm việc theo nhóm (swarm).** Thay vì một agent ôm mọi thứ, ruflo cho các agent tự chia việc. Lợi ích: một yêu cầu như "rà soát repo, viết test, tóm tắt thay đổi" được chia thành nhiều phần nhỏ.
- **Hook tự động định tuyến việc.** Sau khi `init`, theo README bạn chỉ cần dùng Claude Code bình thường. Hệ thống hook tự chuyển việc cho đúng agent, học từ những mẫu làm việc thành công và phối hợp agent ở nền.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ được kinh nghiệm giữa các lần làm việc. README có nói phần học và truy xuất cục bộ bằng vector 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.
- **Máy chủ MCP.** Codex hoặc bất kỳ ứng dụng nào hỗ trợ MCP đều trỏ vào được, nên bạn không bị khoá riêng vào Claude Code.
- **Bảng điều khiển (console).** Đây là "buồng lái" đặt cạnh Claude Code: xem workflow, agent, mô hình, token và chi phí. Bạn mở log và kết quả của từng lần chạy để tìm lỗi, chạy lại, so sánh. Có thể chạy riêng bằng `npx ruflo tui`.
- **Cho Claude lái console, bạn đặt giới hạn.** Trong Settings → Claude control có bốn mức quyền: `read`, `write`, `manage`, `full`, và hai 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á huỷ vẫn phải xác nhận, kể cả ở chế độ `auto`.
- **Hệ thống plugin.** README liệt kê 48 plugin (cộng 3 plugin bên ngoài): bầy agent, RAG và bộ nhớ, sinh test, quét bảo mật, theo dõi chi phí token, tài liệu tự động và nhiều thứ khác.
- **Federation.** Agent trên các máy khác nhau có thể trao đổi với nhau, theo README là không làm lộ dữ liệu. Phần này dành cho người dùng nâng cao, người mới chưa cần đụng.

```note
Một số plugin và "mod" của ruflo chạy với quyền tài khoản của bạn và không bị đóng khung trong sandbox. README khuyên đọc mã nguồn trước khi cài. Hãy làm theo, nhất là trên máy có dữ liệu công việc.
```

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

Chỉ những thứ tư liệu nói rõ:

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json`. Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn dùng đường cài vào dự án. Với đường chỉ cài plugin, README yêu cầu Claude Code **2.1.287 trở lên**. Lệnh cài plugin từ terminal cần bản **2.1.292 trở lên**.
- **Codex hoặc một ứng dụng 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 đó.

Tư liệu không nói rõ yêu cầu hệ điều hành, phần cứng (GPU) hay cách lấy API key cho từng nhà cung cấp mô hình. Phần README bạn đang đọc cũng bị cắt ở giữa, nên nếu cần chi tiết hơn hãy xem `README.md`, thư mục `docs/` và các file `CLAUDE.md`, `AGENTS.md` trong repo.

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

README có nhiều đường cài. Đường nhanh nhất cho người mới là dùng `npx ruflo@latest init`. Hai đường còn lại là cài plugin trong Claude Code, hoặc nối Codex qua MCP.

```steps
- Kiểm tra Node | Đảm bảo máy có Node 20 trở lên
- Mở terminal trong dự án | Vào đúng thư mục dự án của bạn
- Chạy init | Lệnh npx thêm agent, hook, bộ nhớ và MCP vào dự án
- Mở lại Claude Code | Claude Code nạp cấu hình ruflo ở lần khởi động tiếp theo
- Giao việc thử | Dán một yêu cầu mẫu để xem swarm làm việc
```

### Kiểm tra Node đã đủ phiên bản

`package.json` yêu cầu Node từ 20.0.0. Mở terminal (PowerShell trên Windows, Terminal trên macOS) rồi gõ:

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 20, bạn cần cài Node mới hơn trước khi làm tiếp.

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

Đây là chỗ người mới hay vấp. Lệnh `init` ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong thư mục dự án mình muốn dùng, không phải thư mục người dùng chung chung. Ví dụ:

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

Thay phần sau `cd` bằng đường dẫn thật tới dự án của bạn.

### Chạy lệnh init

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

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

Lệnh này tải ruflo bằng `npx` và thêm agent, hook, bộ nhớ và máy chủ MCP vào dự án. Theo bảng so sánh trong README, cách này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings trong dự án của bạn. Nếu dự án đã có `CLAUDE.md` riêng, nên sao lưu trước khi chạy (ví dụ dùng git để commit).

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

Mở Claude Code trong cùng thư mục. README cho biết Claude Code sẽ nạp các thành phần ruflo ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code lúc chạy `init`, hãy đóng và mở lại.

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

Đường này **không thêm file nào vào dự án**. Nó cài công cụ lõi, console trực quan và mod. Gõ từng dòng 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
```

Nếu dùng Claude Code 2.1.292 trở lên, bạn cũng có thể cài từ terminal:

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

Lưu ý từ README: đường plugin chỉ cho một phần chức năng (lệnh slash, vài skill, định nghĩa agent). Bản đầy đủ gồm 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon nằm ở đường `npx ruflo init`.

### Cách khác: nối Codex hoặc ứng dụng MCP

Cấu hình **command** là `npx` và **arguments** là `["-y", "ruflo@latest", "mcp", "start"]`. Nếu bạn viết dưới dạng một dòng lệnh, đó là:

```bash
npx -y ruflo@latest mcp start
```

Cách điền chính xác vào ứng dụng MCP của bạn tuỳ từng ứng dụng. README không hướng dẫn chi tiết, hãy xem tài liệu của chính ứng dụng đó.

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

Theo README, có vài dấu hiệu rõ ràng:

- Sau `npx ruflo@latest init`, trong dự án xuất hiện các thư mục như `.claude/` và `.claude-flow/` cùng file `CLAUDE.md`.
- Mở lại Claude Code rồi gõ `/ruflo`. README ghi rằng với đường cài này bạn mở được console của ruflo bằng lệnh đó.
- Với đường plugin, gõ `/plugin` trong Claude Code. Các mod bạn cài (như ruflo-console, ruflo-mods) phải hiện trong dòng "active mods".
- Muốn xem console mà không cần Claude Code, chạy `npx ruflo tui`. Thêm `--plain` để in ra một khung hình duy nhất, tiện cho script.

Nếu `/ruflo` không nhận ra, hãy đóng và mở lại Claude Code. Với đường plugin, chạy thêm `/reload-plugins`.

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

Các tình huống dưới đây bám theo những gì README mô tả. Kết quả thực tế phụ thuộc vào mô hình và dự án của bạn.

### 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 mới nhận một dự án cũ, ít test, chưa biết đâu là chỗ dễ hỏng. Sau khi `init` và mở lại Claude Code, bạn dán đúng prompt 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.
```

Bạn có thể viết tiếng Việt cho quen tay, nhưng prompt gốc bằng tiếng Anh là cách an toàn nhất để thử lần đầu. Kết quả mong đợi: các agent chia nhau tìm module rủi ro, viết test và tóm tắt những gì đã đổi. Luôn xem lại diff trước khi giữ thay đổi.

> Agent không thông minh hơn nhờ cài thêm công cụ, mà làm được việc dài hơn nhờ có chỗ nhớ và người điều phối.
>
> — Ông T

### Tạo "mission" trong console và giữ quyền kiểm soát

Bối cảnh: bạn muốn thử cho Claude thao tác trên console mà vẫn an toàn. Theo kịch bản mẫu của README: cài console bằng các lệnh plugin ở trên, mở `/ruflo`, vào Settings → Claude control và chọn **write + ask**. Sau đó yêu cầu:

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

Claude sẽ mở trang Missions và đặt mục tiêu. Bạn xác nhận hành động tạo trong console. Kiểm tra bằng cách xem Missions có mục tiêu mới và Overview có ghi lại hành động. README nhấn mạnh: tạo mission **không** có nghĩa tính năng đã được làm. Muốn dừng, bấm **Take back control**, các lệnh gọi sau đó của Claude sẽ bị từ chối cho đến khi bạn trả quyền lại.

### Theo dõi chi phí và chạy nền với plugin

Bối cảnh: bạn dùng AI nhiều và muốn biết token tiêu vào đâu. README có plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí) và `ruflo-loop-workers` (lên lịch tác vụ nền). Cài giống các plugin khác:

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

Tên plugin lấy đúng từ danh sách trong README. Cách dùng từng plugin, bạn nên xem tài liệu riêng của plugin trong thư mục `plugins/` của repo, vì README bản này không mô tả lệnh cụ thể.

### Nối Codex hoặc công cụ MCP khác vào cùng bộ não

Bối cảnh: nhóm bạn dùng Codex chứ không dùng Claude Code. Bạn cấu hình máy chủ MCP với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]` như phần cài đặt đã nêu. Kết quả: công cụ của ruflo hiện ra trong ứng dụng MCP đó để bạn gọi, mà không phải thêm file vào dự án.

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

**Lệnh `npx` báo lỗi hoặc không chạy.** Thường do Node quá cũ hoặc chưa cài. Chạy `node --version`, cần từ 20.0.0 trở lên.

**Lệnh `/plugin` hoặc `/ruflo` không nhận ra trong Claude Code.** Khả năng cao là bản Claude Code cũ. Đường cài plugin cần từ 2.1.287. Hãy cập nhật Claude Code, mở lại rồi thử `/reload-plugins`.

**Cài xong mà Claude Code không dùng được gì mới.** Với đường `init`, README nói Claude Code nạp ở lần khởi động tiếp theo. Hãy đóng hẳn rồi mở lại, và mở đúng thư mục bạn đã chạy `init`.

**Gọi tên công cụ MCP bị lệch.** README lưu ý: plugin `ruflo-core` đăng ký công cụ dưới dạng `mcp__plugin_ruflo-core_ruflo__*`, khác với tên ngắn của đường CLI. Nếu bạn làm theo hướng một trang tin tức cho đường CLI nhưng lại cài bằng plugin, tên công cụ sẽ không khớp. Chọn một đường rồi bám theo tài liệu của đường đó.

**Cài trùng một plugin từ hai marketplace.** 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. Cài từ cả hai, mod và lệnh có thể bị nạp hai lần.

**Cài mod lạ rồi lo về quyền.** Mod chạy bằng quyền tài khoản của bạn, không có sandbox. Đừng cài khi chưa đọc mã. Trong console, giữ mức Claude control ở `read` hoặc `write` kèm `ask` cho tới khi bạn quen.

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

**Điểm mạnh.** Cài đặt ngắn, một lệnh là xong. Dùng được với cả Claude Code lẫn Codex và các ứng dụng MCP. Có nhiều lựa chọn từ nhẹ (chỉ plugin, không thêm file) đến đầy đủ. Console cho bạn nhìn thấy agent, token và chi phí, và có cơ chế phân quyền rõ ràng khi cho Claude điều khiển. Giấy phép MIT, và repo vẫn được cập nhật trong ba tháng gần đây.

**Giới hạn.** Hệ sinh thái rất lớn (hàng chục plugin, hàng trăm công cụ), nên người mới dễ choáng. Đường `init` thêm nhiều file vào dự án. README tự thừa nhận hai đường cài có phạm vi rất khác nhau, và các video minh hoạ dùng dữ liệu mẫu, không chứng minh việc swarm hoàn thành công việc thật. Phần học tự động nên được xem như ý tưởng mô tả (README gọi là "conceptual"), đừng kỳ vọng phép màu. Chi phí gọi mô hình vẫn là của bạn, nên theo dõi token.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần trả lời nhanh hoặc sửa vài file nhỏ, Claude Code thuần là đủ, không cần thêm lớp điều phối. Nếu dự án nhạy cảm và bạn chưa muốn thêm file hay hook, hãy thử đường plugin trước, hoặc dùng thử trên một dự án nháp. Bạn nên bắt đầu bằng một việc nhỏ như prompt rà soát repo ở trên, rồ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 được mà không phải trả phí bản quyền. Tuy nhiên ruflo chạy trên Claude Code, Codex hoặc các nhà cung cấp mô hình khác, nên chi phí dùng mô hình vẫn do tài khoản của bạn chịu. Tư liệu chưa nêu bảng giá cụ thể.

### ruflo cần Node phiên bản nào?

File 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. Nếu dùng đường plugin, Claude Code cần từ bản 2.1.287.

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

Claude Code thuần là một agent làm việc một mình. ruflo thêm lớp điều phối bên ngoài: nhiều agent chuyên biệt, bầy agent phối hợp, bộ nhớ qua nhiều phiên, hook và máy chủ MCP. Sau khi init bạn vẫn dùng Claude Code như cũ, phần điều phối chạy nền theo README.

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

Có. README nói Codex và các MCP client khác dùng được bằng cách cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Cách điền vào từng ứng dụng cụ thể tư liệu chưa hướng dẫn.

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

Đường plugin không thêm file nào vào dự án, nhưng chỉ cho lệnh slash, vài skill và định nghĩa agent. Đường npx init thêm file như .claude/ và CLAUDE.md, đổi lại có đầy đủ agent, lệnh, skill, hook, máy chủ MCP và daemon. README khuyên đường init cho việc dùng nghiêm túc.

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

Có cơ chế giới hạn: 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. Hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả khi auto, và bạn có nút Take back control để dừng ngay.

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

Phần README bạn đang xem không nói rõ yêu cầu GPU hay hệ điều hành. Chỉ biết cần Node 20 trở lên. Hãy xem thêm README đầy đủ và thư mục docs trong repo để biết chi tiết.
