# 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, swarm, bộ nhớ lâu dài và máy chủ MCP. Bạn chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng bộ công cụ rất rộng nên nên bắt đầu từ một tác vụ nhỏ.

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

Ruflo là một "agent meta-harness" cho Claude Code và Codex: một lớp công cụ bao quanh mô hình AI để nó làm việc có tổ chức hơn. Tác giả mô tả bằng một công thức ngắn: Agent = Model + Harness. Mô hình lo viết code, còn harness lo công cụ, bộ nhớ, vòng lặp và các giới hạn an toàn. Ruflo là phần harness đó.

Nếu bạn đang dùng Claude Code và thấy mỗi phiên làm việc đều phải giải thích lại từ đầu, hoặc muốn nhiều agent chia nhau việc thay vì một agent làm hết, thì đây là repo đáng thử. Repo hiện có khoảng 81.582 sao và 9.607 fork, giấy phép MIT, viết chủ yếu bằng TypeScript. Tác giả là Reuven Cohen (rUv), dự án khởi đầu với tên Claude Flow rồi đổi tên thành Ruflo.

Đ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 406 công cụ MCP hay 61 lệnh CLI. Sau khi `init`, hệ thống hook tự định tuyến tác vụ và điều phối agent ở phía sau.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung (harness) thêm agent, swarm, 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ì

Bạn không cần dùng hết. Dưới đây là những phần có ích nhất cho người mới, theo đúng những gì README mô tả.

### Thêm agent, lệnh, kỹ năng và hook vào dự án

Sau `init`, dự án của bạn có thêm agent, hook, bộ nhớ và một MCP server. Theo bảng so sánh trong README, cách cài bằng CLI cho bạn 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon. Claude Code sẽ nhận các thứ này ở lần khởi động kế tiếp. Lợi ích thực tế: bạn có sẵn "đội" agent chuyên biệt mà không phải tự viết từng file cấu hình.

### Swarm: nhiều agent chia việc

Thay vì một agent làm tuần tự, Ruflo cho các agent tự tổ chức thành swarm (đàn, nhóm). Ví dụ trong README là yêu cầu "dùng một swarm của ruflo để rà soát repo, tìm module rủi ro nhất, viết test và tóm tắt thay đổi". Với việc lớn, chia nhóm giúp bạn đỡ phải điều phối từng bước.

### Bộ nhớ qua nhiều phiên

Ruflo có bộ nhớ để agent nhớ giữa các phiên làm việc, và các plugin như `ruflo-agentdb`, `ruflo-rag-memory`, `ruflo-rvf` phục vụ việc lưu, truy xuất và khôi phục. README lưu ý phần "tự học" chỉ là mô hình khái niệm: truy xuất vector cục bộ có thể chạy không cần LLM, nhưng embedding và các module học đã cấu hình vẫn cần có.

### Bảng điều khiển ngay trong Claude Code

Plugin `ruflo-console` là một "cockpit": theo dõi workflow, agent, mô hình, token và chi phí bên cạnh Claude Code. Bạn mở bằng lệnh `/ruflo`. Có thể xem log agent, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Bảng điều khiển cũng chạy riêng ngoài Claude Code bằng `npx ruflo tui`.

### Cho Claude lái, 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`, cùng chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Hành động vượt quyền sẽ bị từ chối, còn 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`. Nút "Take back control" dừng ngay quyền điều khiển của Claude.

### Hơn 48 plugin theo nhóm việc

README liệt kê 48 plugin, chia theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ, học và trí tuệ, kiểm thử (testgen, browser), bảo mật (security-audit, aidefence), kiến trúc, DevOps (theo dõi chi phí token) và công cụ tạo plugin riêng. Bạn chỉ cài cái mình cần.

### Dùng được với Codex và client MCP khác

Không chỉ Claude Code. Codex và các client MCP khác có thể trỏ vào `npx -y ruflo@latest mcp start`. README cũng có lệnh `npx ruflo init --grok` cho Grok Build.

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

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

- **Node.js từ 20.0.0 trở lên.** `package.json` của gói yêu cầu như vậy, và các lệnh đều chạy qua `npx`.
- **Claude Code** (hoặc Codex, hoặc một client MCP khác) nếu bạn muốn dùng Ruflo ở vai trò harness.
- **Claude Code 2.1.287 trở lên** nếu chọn cách cài bằng plugin. Lệnh cài từ terminal (`claude plugin install ...`) cần bản 2.1.292 trở lên.
- Một thư mục dự án để chạy `init`.

Tư liệu không nói rõ yêu cầu về hệ điều hành, phần cứng hay API key riêng cho phần cài đặt cơ bản. Bản thân Claude Code hay Codex vẫn cần tài khoản của chúng như bình thường. Nếu bạn bật các module học hoặc embedding, README nói chúng "vẫn cần có" nhưng không nêu chi tiết cần gì, nên hãy xem thêm trong thư mục `docs/` của repo.

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

Có ba đường: `init` bằng CLI (đầy đủ nhất), plugin cho Claude Code (nhẹ hơn, không thêm file vào dự án), và cấu hình MCP cho client khác. Mình hướng dẫn đường CLI trước vì README khuyên nó cho việc dùng thật.

```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 bạn muốn dùng Ruflo
- Chạy init | Chạy một lệnh để thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude Code | Khởi động Claude Code trong cùng thư mục
- Giao một tác vụ thật | Gõ yêu cầu mẫu để thử swarm
```

### Kiểm tra Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và chạy:

```bash
node --version
```

Kết quả phải là v20 trở lên. Nếu thấp hơn hoặc báo không tìm thấy lệnh, bạn cần cài hoặc nâng cấp Node trước. Đây là chỗ người mới hay vấp nhất.

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

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 của mình, 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 `duong-dan-toi-du-an-cua-ban` bằng đường dẫn thật của bạn.

### Chạy init

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

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

Lệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh trong README, bạn sẽ thấy xuất hiện các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings. Nếu thư mục dự án của bạn đã có `CLAUDE.md` riêng, hãy sao lưu hoặc dùng git để xem lại thay đổi sau khi chạy.

Muốn cài 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 và giao tác vụ

Mở Claude Code trong cùng thư mục. Nếu nó đang mở sẵn, hãy thoát và mở lại để nhận cấu hình mới. Rồi thử yêu 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.
```

Bạn có thể viết bằng tiếng Việt nếu muốn, nhưng câu mẫu trên là câu đã được README dùng.

### Cách khác: cài bằng plugin Claude Code

Cách này không thêm file nào vào dự án. Chạy các lệnh 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
```

Giải thích nhanh: lệnh đầu thêm "chợ" plugin của Ruflo, ba lệnh `install` cài lõi, bảng điều khiển và mods, `/reload-plugins` nạp lại, còn `/ruflo` mở bảng điều khiển. Nếu từ terminal và Claude Code bản 2.1.292 trở lên, README cho phép:

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

```note
Mods chạy với quyền của tài khoản bạn và không bị sandbox. README khuyên đọc mã của mod trước khi cài. Hãy làm đúng như vậy, nhất là trên máy có dữ liệu công việc quan trọng.
```

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

Không cần thiết lập dự án. Trong phần cấu hình MCP của client, đặt **command** là `npx` và **arguments** là:

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

Bạn cần tìm đúng chỗ khai báo MCP server trong client của mình. README không hướng dẫn riêng cho từng client.

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

README không đưa ra một lệnh "kiểm tra" riêng, nhưng có vài dấu hiệu rõ ràng theo tư liệu:

- Sau `init`, thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Mở lại Claude Code, gõ `/ruflo` để mở bảng điều khiển. README gợi ý chu trình: `npx ruflo init`, khởi động lại Claude Code, rồi `/ruflo`.
- Với cách cài plugin, gõ `/plugin` để xem các mod có xuất hiện trong dòng "active mods".
- Chạy `npx ruflo tui` để mở bảng điều khiển độc lập trong terminal. Thêm `--plain` để in ra đúng một khung, tiện cho script.

Thử nhanh nhất: giao tác vụ mẫu ở trên và xem Claude Code có dùng agent hoặc swarm của Ruflo hay không. Nếu bạn muốn kiểm tra mà chưa tin tưởng việc thay đổi file, các lệnh như `npx ruflo init --grok --dry-run` cho thấy ý tưởng "xem trước": README nói cờ `--dry-run` dùng để xem trước phần ghi file (ở đó là cho Grok).

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

README nhấn mạnh Ruflo mạnh nhất khi bạn giao cho nó việc có nhiều bước. Dưới đây là các tình huống bám đúng khả năng được mô tả.

### Dev mới nhận một repo lạ cần rà soát nhanh

Bạn vừa nhận một dự án chưa quen. Chạy `npx ruflo@latest init` trong thư mục dự án, mở Claude Code và 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: các agent chia việc tìm module rủi ro, viết test cho nó và tóm tắt những gì đã đổi. Bạn đọc phần tóm tắt, xem diff trước khi giữ lại thay đổi nào.

> Agent không chỉ chạy, mà còn biết phối hợp với nhau.
>
> — Ông T

### Người làm sản phẩm muốn theo dõi agent và chi phí

Bạn không rành code nhưng muốn biết AI đang làm gì và tốn bao nhiêu token. Cài bằng đường plugin: thêm marketplace rồi cài `ruflo-console`, `ruflo-mods`, nạp lại bằng `/reload-plugins` và gõ `/ruflo`. Bảng điều khiển hiển thị workflow, agent, mô hình, token và chi phí bên cạnh Claude Code. Nhờ vậy bạn nhìn thấy thay vì đoán.

### Để Claude tạo "mission" trong bảng điều khiển, có kiểm soát

Đây là bài tập an toàn trong README. Làm theo thứ tự:

1. Mở `/ruflo`, vào Settings → Claude control, chọn **write + ask**.
2. Gõ: "Create a mission to add a dark mode toggle. Show me the mission and its status."
3. Khi Claude mở mục Missions và đặt mục tiêu, bạn xác nhận hành động tạo.
4. Kiểm tra Missions đã có mục tiêu và Overview đã ghi lại hành động.

Lưu ý README nói rõ: tạo mission không có nghĩa là tính năng đã được làm xong. Bạn đang tập cách giao quyền có giới hạn, không phải xem phép màu.

### Dùng Ruflo từ Codex hoặc công cụ khác

Nếu nhóm bạn dùng Codex hoặc một client MCP khác, cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Client đó có thể gọi các công cụ của Ruflo (bộ nhớ, swarm…) mà không cần thêm file vào dự án.

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

Các lỗi dưới đây là những điểm rất dễ gặp với loại công cụ này, xây trên các yêu cầu có trong tư liệu.

### `npx` báo lỗi hoặc lệnh không chạy

Thường do Node cũ hơn yêu cầu (cần 20 trở lên) hoặc chưa cài Node. Chạy `node --version`, nâng cấp Node nếu cần rồi chạy lại lệnh `init`.

### Mở Claude Code mà không thấy gì 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 rồi mở lại trong đúng thư mục đã chạy `init`. Nếu dùng plugin, thử `/reload-plugins`. Nếu vẫn chưa có, hãy kiểm tra xem bạn có đang đứng đúng thư mục dự án khi chạy `init` không.

### Lệnh `/plugin install` hoặc `claude plugin install` không nhận

Cách plugin cần Claude Code từ 2.1.287 trở lên, và lệnh từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước.

### Plugin chạy lặp hoặc xung đột

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 duy nhất. Nếu bật từ cả hai nơi, mod và lệnh có thể bị nạp hai lần.

### Chi phí và quyền hạn vượt ý muốn

Swarm nhiều agent có thể dùng nhiều token hơn một agent đơn. Giữ mức quyền thấp (read hoặc write với chế độ `ask`), bật theo dõi chi phí và xem bảng điều khiển. Nếu thấy agent làm điều bạn không muốn, dùng nút "Take back control".

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

**Điểm mạnh.** Cài đặt bằng một lệnh, giấy phép MIT, repo còn được cập nhật trong vài tháng gần đây. Bạn có sẵn agent, bộ nhớ, bảng điều khiển và hệ thống phân quyền để giao việc có giới hạn. Hỗ trợ cả Claude Code, Codex và client MCP khác nên không bị khoá vào một công cụ.

**Giới hạn.** Bộ công cụ rất rộng (48 plugin, hàng trăm công cụ MCP), nên người mới dễ choáng. README còn nói thẳng nhiều phần chỉ là mô hình khái niệm hoặc dùng dữ liệu mẫu trong bản demo, không phải bằng chứng việc đã hoàn thành. Cài bằng `init` thêm khá nhiều file vào dự án. Tư liệu chưa nêu rõ yêu cầu hệ điều hành hay phần cứng.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code làm vài việc nhỏ, dùng Claude Code thuần là đủ. Nếu bạn muốn thử nhẹ, cài một plugin lẻ (zero file trong dự án) rồi mới quyết định có chạy `init` đầy đủ hay không. Nếu bạn quản lý dữ liệu nhạy cảm, hãy đọc kỹ mã mod và mức quyền trước khi bật.

Lời khuyên của mình: chạy thử trên một dự án nhỏ, giữ mức quyền thấp, giao đúng một tác vụ như câu mẫu và xem kết quả trước khi 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. Tuy nhiên Ruflo chạy cùng Claude Code, Codex hoặc các nhà cung cấp AI khác, và chi phí của những dịch vụ đó là riêng. Tư liệu không nói gì thêm về gói trả phí của Ruflo.

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

File package.json yêu cầu Node từ 20.0.0 trở lên. Các lệnh cài đặt trong README đều chạy qua npx nên bạn cần Node và npm hoạt động bình thường.

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

Ruflo là lớp bao quanh Claude Code: 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 mô tả nó theo công thức Agent = Model + Harness, trong đó Ruflo là phần harness. Nếu bạn chỉ làm việc nhỏ, Claude Code thuần có thể đã đủ.

### Cài bằng init và cài bằng plugin khác nhau thế nào?

Cách plugin không thêm file nào vào dự án và chỉ cho slash command, vài skill, định nghĩa agent. Cách `npx ruflo init` thêm .claude/, .claude-flow/, CLAUDE.md và cho vòng làm việc đầy đủ gồm hook, MCP server và daemon. README khuyên cách init cho dùng thật.

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

Có. README nói Codex và các client MCP khác dùng được: đặt command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. README cũng có lệnh init riêng cho Grok Build.

### Cho Claude điều khiển bảng điều khiển có nguy hiểm 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 mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận ngay cả khi ở auto, và có nút Take back control để dừng. Riêng mods thì không bị sandbox, nên cần đọc mã trước khi cài.

### Có cần GPU hoặc cấu hình mạnh không?

Tư liệu không nêu yêu cầu phần cứng cho phần cài đặt cơ bản. Một số plugin nhắc đến tìm kiếm tăng tốc bằng GPU hoặc chạy mô hình cục bộ, nhưng đó là phần tuỳ chọn và chưa có thông tin chi tiết trong tư liệu này.
