# 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 bao quanh Claude Code hoặc Codex, bổ sung nhiều agent chuyên biệt, swarm phối hợp, bộ nhớ qua các phiên và MCP server. Cài chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Với người mới, bạn cứ dùng Claude Code như bình thường, phần điều phối chạy nền.

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

ruflo là một "agent harness", tức lớp công cụ bao quanh Claude Code hoặc Codex để AI làm việc có tổ chức hơn. README mô tả nó là một agent meta-harness. Nó thêm các agent chuyên biệt, hook, bộ nhớ và MCP server vào dự án của bạn. Nhờ đó AI không chỉ trả lời từng câu lẻ mà biết chia việc, nhớ lại và phối hợp.

Repo này do Reuven Cohen (rUv) xây dựng, ban đầu có tên Claude Flow. Hiện repo có khoảng 81.588 sao và 9.608 fork, giấy phép MIT, viết chủ yếu bằng TypeScript và vẫn được cập nhật trong 3 tháng gần đây. Người nên quan tâm là lập trình viên đang dùng Claude Code hoặc Codex hằng ngày, và muốn giao cho AI những việc lớn hơn như rà soát cả repo, viết test, theo dõi chi phí.

Điểm đáng giá nhất là cách cài: một lệnh `npx ruflo@latest init` trong thư mục dự án. README còn nhắn người mới rằng bạn không cần học hết hàng trăm công cụ MCP và lệnh CLI. Sau `init`, bạn cứ dùng Claude Code bình thường, phần hook sẽ tự điều phối ở nền.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) thêm agent, bộ nhớ, hook và MCP server cho Claude Code và Codex, cài bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Công thức README dùng là "Agent = Model + Harness". Mô hình lo phần viết, còn harness cấp công cụ, bộ nhớ, vòng lặp và các giới hạn kiểm soát. Dưới đây là những thứ chính, theo cách hiểu thực tế.

- **Nhiều agent chuyên biệt.** README nêu bản cài bằng CLI có 98 agent, hơn 60 lệnh và 30 skill. Bạn có thể giao việc cho "đội" thay vì một AI làm hết.
- **Swarm (đàn agent) phối hợp.** Các agent tự chia việc, ví dụ một agent tìm module rủi ro, một agent viết test. Bạn mô tả mục tiêu, ruflo lo chia nhỏ.
- **Bộ nhớ qua các phiên.** Agent có thể nhớ điều đã học ở lần làm trước, nên lần sau không phải giải thích lại từ đầu. README cũng nhắc phần 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ấu hình.
- **MCP server.** Claude Code, Codex hoặc client MCP khác có thể gọi các công cụ của ruflo qua một lệnh khởi động chung.
- **Bảng điều khiển (console) ngay cạnh Claude Code.** Theo dõi workflow, agent, model, token và chi phí. Mở log và kết quả của từng lần chạy để tìm lỗi, xem lại, so sánh.
- **Cho Claude điều khiển bảng điều khiển, nhưng bạn đặt giới hạn.** Trong Settings có mục Claude control với các mức `read`, `write`, `manage`, `full`, kèm 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`.
- **Kho plugin.** README liệt kê 48 plugin, chia nhóm như đ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à đặt ngân sách, ruflo-security-audit quét lỗ hổng.
- **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. Đây là tính năng nâng cao, người mới chưa cần.

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

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

- **Node.js từ phiên bản 20.0.0 trở lên.** package.json của repo yêu cầu như vậy. Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn muốn dùng đường cài chính. Riêng đường cài chỉ bằng plugin cần Claude Code **2.1.287 trở lên**. Lệnh cài từ terminal (`claude plugin install`) cần **2.1.292 trở lên**.
- Codex hoặc client MCP khác cũng dùng được, README bảo trỏ chúng tới lệnh khởi động MCP của ruflo.
- Một thư mục dự án để chạy `init`.

Tư liệu không ghi yêu cầu về GPU, hệ điều hành cụ thể hay API key riêng cho ruflo. Bản thân Claude Code hoặc Codex thì bạn cần đã đăng nhập và dùng được như bình thường.

```note
Mod của ruflo chạy với quyền tài khoản của bạn và không nằm trong sandbox. README khuyên đọc mã trước khi cài. Hãy giữ Claude control ở mức read + ask khi mới thử, và chỉ nâng quyền khi bạn đã hiểu mình đang cho phép gì.
```

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

README có hai đường cài khác nhau về "độ sâu". Đường CLI (`npx ruflo init`) cho đầy đủ vòng lặp: agent, lệnh, skill, MCP server, hook và daemon, đổi lại nó thêm file vào dự án (`.claude/`, `.claude-flow/`, `CLAUDE.md`, settings). Đường plugin thì nhẹ hơn, không thêm file nào vào workspace. README ghi đường CLI hợp với dùng nghiêm túc, đường plugin hợp để thử từng phầ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
- Khởi động lại Claude Code | Để Claude Code nhận cấu hình mới
- Giao một việc thật | Dùng câu lệnh mẫu để 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: lệnh `init` ghi file vào **thư mục hiện tại**. Vì vậy hãy mở terminal đúng thư mục dự án (hoặc thư mục thử nghiệm). Đừng chạy ở thư mục chứa nhiều thứ không liên quan.

```powershell
cd đường-dẫn-tới-dự-án-của-bạn
```

### Chạy lệnh init

Đây là lệnh chính trong README. Lệnh thêm agent, hook, bộ nhớ và MCP server của ruflo vào dự án.

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

`npx` tải và chạy ruflo mà không cần cài toàn cụ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
```

### Khởi động lại Claude Code và giao việc

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thành phần mới ở lần khởi động kế tiếp. Rồi đưa cho nó một việc thật, ví dụ 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.
```

Câu này bảo Claude dùng swarm của ruflo để rà soát repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn có thể viết bằng tiếng Việt, nhưng hãy giữ cụm "ruflo swarm" để Claude hiểu là cần dùng bộ công cụ này.

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

Nếu bạn không muốn thêm file vào dự án, chạy các lệnh sau **bên trong Claude Code** (không phải terminal thường):

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo
```

Dòng đầu thêm "chợ" plugin của ruflo. Ba dòng `install` cài phần lõi, bảng điều khiển và mod. `/reload-plugins` nạp lại, còn `/ruflo` mở bảng điều khiển. README cho biết `ruflo-core` có kèm MCP server riêng. Nếu 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

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

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

README cũng ghi lệnh tương đương trên một dòng:

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

### Cách khác: chạy bảng điều khiển trong terminal thường

Bảng điều khiển chạy độc lập, không cần Claude Code:

```bash
npx ruflo tui
```

Thêm `--plain` nếu bạn muốn in ra một khung hình để dùng trong 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:

- Sau `npx ruflo@latest init`, thư mục dự án xuất hiện các thành phần như `.claude/`, `.claude-flow/` và `CLAUDE.md` (README liệt kê các mục này cho đường cài CLI).
- Khởi động lại Claude Code rồi gõ `/ruflo`. Nếu bảng điều khiển hiện ra là ổn.
- Với đường plugin, mở `/plugin` và xem các mod có nằm trong dòng "active mods" không.
- Với client MCP, thấy các công cụ của ruflo xuất hiện sau khi cấu hình lệnh khởi động.

Riêng `ruflo-core` cài qua plugin, tên công cụ có dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, khác tên ngắn của đường CLI. Đừng lo nếu thấy hai kiểu tên khác nhau, README đã giải thích điều này.

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

Bạn không cần thuộc hết lệnh. Phần dưới là vài tình huống bám đúng những gì README mô tả.

### Rà soát một dự án lạ trước khi nhận việc

Bạn là lập trình viên mới vào dự án và chưa biết chỗ nào dễ hỏng. Chạy `npx ruflo@latest init` trong thư mục dự án, mở lại Claude Code, rồi dùng đúng câu mẫu của README: nhờ swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Kết quả mong đợi là danh sách thay đổi kèm test mới mà bạn có thể đọc lại và tự duyệt trước khi giữ.

> Bạn vẫn viết code như cũ. ruflo lo phần phối hợp phía sau.
>
> — Ông T

### Theo dõi chi phí và tiến độ ngay cạnh Claude Code

Bạn là chủ một nhóm nhỏ và lo AI "đốt" token mà không biết. Cài `ruflo-console` bằng các lệnh plugin ở trên, rồi gõ `/ruflo`. Bảng điều khiển cho thấy workflow, agent, model, token và chi phí. README còn có plugin `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo. Kết quả là bạn thấy việc nào tốn nhiều, thay vì chỉ biết hoá đơn cuối tháng.

### Để Claude tạo "mission" nhưng bạn giữ quyền duyệt

README có một bài thử an toàn. Mở `/ruflo`, vào Settings, chọn Claude control rồi đặt write + ask. Sau đó nhắn:

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

Claude mở mục Missions và đặt mục tiêu, còn bạn xác nhận hành động tạo. Hãy kiểm tra Missions có mục tiêu mới và Overview có ghi lại hành động. Lưu ý README nhấn mạnh: tạo mission không có nghĩa tính năng đã được làm xong. Nếu cần dừng, bấm **Take back control**, các lệnh sau đó của Claude sẽ bị từ chối cho đến khi bạn trả quyền lại.

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

Bạn dùng Codex thay vì Claude Code. Trong phần cấu hình MCP, điền command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Kết quả là client đó gọi được bộ công cụ của ruflo mà không phải thiết lập dự án. Nếu muốn thiết lập dự án có hướng dẫn, chạy `npx ruflo@latest init wizard`.

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

Tư liệu không có mục xử lý lỗi riêng, nên các điểm dưới đây là những chỗ rất dễ vấp với loại công cụ này, dựa trên chính yêu cầu mà README nêu.

- **Lệnh `npx` báo lỗi hoặc không chạy.** Kiểm tra Node bằng `node --version`. Repo yêu cầu Node 20.0.0 trở lên, nếu thấp hơn hãy nâng cấp rồi chạy lại.
- **Gõ `/plugin ...` trong terminal thường không có tác dụng.** Các lệnh bắt đầu bằng dấu `/` là lệnh trong Claude Code. Hãy gõ chúng sau khi mở Claude Code. Chỉ lệnh `claude plugin install ...` mới chạy được từ terminal.
- **Lệnh plugin bị báo không hợp lệ.** README yêu cầu Claude Code 2.1.287 trở lên cho đường plugin, và 2.1.292 trở lên cho lệnh từ terminal. Hãy cập nhật Claude Code trước.
- **Khởi động xong vẫn không thấy tính năng của ruflo.** Sau `init`, phải khởi động lại Claude Code. Sau khi cài plugin thì chạy `/reload-plugins`. Hãy chắc là bạn mở Claude Code đúng thư mục đã chạy `init`.
- **Cài cùng một plugin ngoài từ hai marketplace.** README cảnh báo với các plugin ngoài như agentic-qe-fleet, agentdb và agentic-flow, nếu bật từ cả hai nơi thì mod và lệnh bị nạp hai lần. Chỉ cài từ một nơi.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có lộ trình từ nhẹ (plugin) đến đầy đủ (CLI). Có bảng điều khiển để theo dõi agent, token, chi phí. Cơ chế quyền hạn của Claude control khá rõ ràng: mặc định read + ask, và các hành động nhạy cảm vẫn cần xác nhận. Giấy phép MIT, repo đông người dùng và còn cập nhật.

**Giới hạn.** Phạm vi rất rộng (48 plugin, hàng trăm công cụ), nên người mới dễ choáng. Đường cài CLI thêm khá nhiều file vào dự án. Mod chạy với quyền tài khoản của bạn và không có sandbox. README cũng nói rõ các bản demo hoạt hình dùng dữ liệu mẫu, không phải bằng chứng về việc swarm đã làm xong việc thật hay bộ nhớ đã nhớ lại đúng. Hãy tự kiểm tra kết quả như với mọi đầu ra của AI.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code trả lời vài câu hỏi đơn giản trong một file, bộ khung này là thừa. Nếu bạn muốn thử nhẹ, hãy bắt đầu với đường plugin `ruflo-core` thay vì `init`. Với một dự án quan trọng, nên thử ở nhánh hoặc thư mục sao chép trước, rồi mới áp dụng vào dự án chính.

## 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ề chi phí của dịch vụ AI phía sau, tức là gói Claude Code hay Codex bạn đang dùng vẫn tính phí theo cách của chúng. README có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

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

Tư liệu không nêu yêu cầu GPU cho phần cài cơ bản. Có một plugin tên ruflo-ruvector được mô tả là tìm kiếm tăng tốc bằng GPU, nhưng đó là plugin tuỳ chọn. Đường cài chính chỉ cần Node 20 trở lên.

### Cài ruflo bằng lệnh nào?

Trong thư mục dự án, chạy `npx ruflo@latest init`, rồi mở lại Claude Code. Nếu muốn không thêm file vào dự án, bạn có thể cài plugin trong Claude Code bằng `/plugin marketplace add ruvnet/ruflo` rồi `/plugin install ruflo-core@ruflo`.

### ruflo có chạy được với Codex, không chỉ Claude Code?

Có. README nói Codex và các client MCP khác dùng được: cấu hình command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`. Tư liệu cũng nhắc tới tích hợp Grok Build qua `npx ruflo init --grok`.

### Chạy trên Windows được không?

Tư liệu không nêu rõ hệ điều hành hỗ trợ. Các lệnh cài đều là `npx`, chạy trên Node 20 trở lên, nên về nguyên tắc bạn có thể thử trên Windows. Tuy vậy chưa có thông tin chính thức, bạn nên thử ở thư mục thử nghiệm trước.

### Dữ liệu của tôi có an toàn không?

README nêu các cơ chế kiểm soát như mức quyền read, write, manage, full, chế độ duyệt ask hoặc auto, và yêu cầu xác nhận với hành động liên quan mạng, chi tiêu hay phá huỷ. Tuy nhiên mod chạy với quyền tài khoản của bạn và không có sandbox, nên cần đọc mã trước khi cài. Tư liệu chưa có thêm chi tiết về cách lưu trữ dữ liệu.

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

Claude Code thuần là một agent làm việc đơn lẻ. ruflo là lớp bao quanh, thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook, MCP server và bảng điều khiển. README nhấn mạnh sau khi cài, bạn vẫn dùng Claude Code như bình thường và phần điều phối chạy ở nền.
