# ruflo: điều phối nhiều agent AI 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 mã nguồn mở: lớp công cụ bọc quanh Claude Code và Codex để thêm agent chuyên biệt, swarm, bộ nhớ dài hạ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ễ: cần Node 20 trở lên và chạy một lệnh npx ruflo@latest init trong thư mục dự án.

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

ruflo là một "agent harness" mã nguồn mở, tức là bộ khung đặt quanh Claude Code hoặc Codex để mô hình AI không chỉ trả lời mà còn có công cụ, trí nhớ và cách phối hợp nhiều agent với nhau. Tác giả mô tả nó bằng một câu: Agent = Model + Harness. Mô hình lo viết code, còn harness lo giao việc, mang ngữ cảnh qua từng bước và kiểm tra kết quả. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.600 sao và khoảng 9.600 fork trên GitHub, giấy phép MIT.

Vấn đề nó giải quyết rất đời thường. Khi dùng Claude Code cho dự án lớn, bạn hay gặp cảnh mỗi phiên làm việc lại bắt đầu từ đầu, AI quên những gì đã làm hôm qua, và một việc phức tạp phải tự chia nhỏ bằng tay. ruflo thêm vào dự án các agent chuyên biệt, hook tự định tuyến tác vụ, bộ nhớ lưu giữa các phiên và một MCP server để Claude Code gọi tới.

Người nên thử là lập trình viên đã quen Claude Code hoặc Codex và muốn nó làm việc có hệ thống hơn. Điểm đáng giá nhất theo README: bạn không cần học hết hàng trăm công cụ. Sau khi chạy `init`, cứ dùng Claude Code như bình thường, phần điều phối chạy ngầm. Người làm văn phòng không viết code vẫn có thể đọc để hiểu ý tưởng, nhưng công cụ này thiên về dự án phần mềm.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) bọc quanh Claude Code và Codex: thêm agent, bộ nhớ, swarm và MCP server vào dự án chỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README giới thiệu khá nhiều thứ. Mình chọn những phần có lợi ích rõ nhất cho người mới.

**Thêm agent và swarm vào Claude Code.** Một swarm là nhóm agent chia việc cho nhau. Bạn chỉ cần nói "dùng swarm của ruflo để xem lại repo này" thay vì tự giao từng việc nhỏ. README nói bản cài đầy đủ có 98 agent, hơn 60 lệnh và 30 skill.

**Bộ nhớ qua nhiều phiên.** ruflo có phần nhớ dựa trên cơ sở dữ liệu vector, để agent lưu và tìm lại kinh nghiệm cũ. Lợi ích: hôm sau mở lại dự án, AI không phải học lại từ đầu. README cũng nói rõ phần "tự học" là mô hình khái niệm, và việc tìm kiếm vector cục bộ vẫn cần embedding cùng các module học được cấu hình.

**Hook tự định tuyến.** Sau khi cài, hook sẽ định tuyến tác vụ và ghi nhận mẫu làm việc thành công ở chế độ nền. Bạn không phải gõ lệnh riêng cho từng việc.

**MCP server.** Đây là cổng để các công cụ khác cắm vào. Codex hay bất kỳ MCP client nào cũng dùng được bằng lệnh `npx -y ruflo@latest mcp start`.

**Bảng điều khiển (console) trong Claude Code.** Gõ `/ruflo` để xem workflow, agent, model, token và chi phí ngay cạnh Claude Code. Bạn có thể mở log, tìm kiếm, xem lại và so sánh các lần chạy. Ngoài ra còn chạy riêng trong terminal bằng `npx ruflo tui`.

**Kho plugin.** README liệt kê 48 plugin, chia theo nhóm: điều phối, bộ nhớ, học máy, 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.

**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. Phần này nâng cao, người mới chưa cần đụng tới.

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

Tư liệu chỉ nói những điều sau:

- **Node.js từ phiên bản 20 trở lên.** `package.json` của repo yêu cầu Node >=20.0.0. Đây cũng là lý do lệnh `npx` chạy được.
- **Claude Code** nếu bạn muốn dùng đường cài chính. Riêng đường cài bằng plugin cần 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 MCP client khác** nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy lệnh trong đó.

README không nói rõ về hệ điều hành, yêu cầu phần cứng hay GPU. Phần API key và tài khoản cho từng nhà cung cấp AI cũng chưa được ghi trong đoạn README mình có. Bạn nên xem thêm hướng dẫn trong thư mục `docs/` của repo trước khi dùng cho việc quan trọng.

```note
Các mod của ruflo chạy với quyền của tài khoản bạn và không được đặt trong sandbox. README khuyên đọc code trước khi cài. Hãy thử trên một dự án không chứa dữ liệu nhạy cảm trước.
```

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

Có nhiều đường cài. Đường đơn giản và đầy đủ nhất là chạy `npx ruflo@latest init` trong thư mục dự án.

```steps
- Mở terminal đúng chỗ | Mở terminal và vào thư mục dự án của bạn
- Chạy init | Chạy npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Khởi động lại Claude Code | Mở 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 | Dán một câu lệnh mẫu để thử swarm
- Tuỳ chọn: cài bằng plugin | Dùng /plugin nếu không muốn thêm file vào dự án
```

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

Đây là chỗ người mới hay vấp nhất: lệnh phải chạy **trong thư mục dự án của bạn**, không phải ở thư mục bất kỳ. Trên Windows, bạn có thể mở thư mục dự án rồi gõ `powershell` vào thanh địa chỉ, hoặc dùng terminal của VS Code. Kiểm tra Node trước:

```bash
node --version
```

Kết quả phải là v20 trở lên. Nếu thấp hơn, hãy cập nhật Node trước khi làm tiếp.

### Chạy lệnh init

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

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

`npx` tải ruflo về chạy tạm, không cần cài toàn cục. Lệnh `init` thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh trong README, bản này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng một số file hỗ trợ và settings. Nghĩa là dự án của bạn sẽ có thêm file, nên nếu dùng git, bạn có thể xem lại thay đổi trước khi commit.

Nếu muốn thiết lập từng bước theo kiểu hỏi đáp, README có lệnh:

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

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

Mở Claude Code trong cùng thư mục. Claude Code sẽ nhận cấu hình mới ở lần khởi động kế tiếp. Rồi dán 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 nhờ swarm 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ỉ chắc câu tiếng Anh trên là câu README đã dùng.

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

Nếu không muốn thêm file nào vào dự án, dùng đường plugin. Cách này cài công cụ lõi, console trực quan và các mod, và không thêm file vào dự án. Gõ lần lượt 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 bạn dùng Claude Code 2.1.292 trở lên, có thể cài từ terminal:

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

Lưu ý README nói rõ: bản plugin chỉ là bản "lite" gồm lệnh slash và vài skill. Muốn có đầy đủ hook, daemon và MCP server theo đúng tài liệu thì dùng `npx ruflo@latest init`.

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

Cấu hình **command** là `npx` và **arguments** như sau:

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

Nơi điền các giá trị này tuỳ từng ứng dụng, thường là mục cấu hình MCP server của nó. README không hướng dẫn chi tiết cho từng ứng dụng.

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

Có vài 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à thư mục dự án có thêm các mục như `.claude/` và `CLAUDE.md`.
2. Sau khi khởi động lại Claude Code, gõ `/ruflo` để mở console. Nếu thấy bảng điều khiển hiện ra là cài thành công.
3. Với đường plugin, gõ `/plugin` và xem ruflo có nằm trong dòng mod đang hoạt động không. README cũng nói đây là cách xác nhận.
4. Không cần Claude Code, bạn có thể thử giao diện terminal riêng:

```bash
npx ruflo tui
```

Thêm `--plain` nếu muốn in ra một khung duy nhất cho script.

README chưa nêu một dòng kết quả cố định để so sánh sau lệnh `init`, nên bạn hãy dựa vào các dấu hiệu trên.

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

### Dev nhận dự án cũ, cần biết chỗ nào dễ hỏng

Bạn vừa nhận một repo cũ, ít test, không ai nhớ module nào nguy hiểm. Chạy `npx ruflo@latest init`, mở lại Claude Code rồi dán câu mẫu:

```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 điều phối các agent, chỉ ra module rủi ro nhất, viết test và tóm tắt những gì đã đổi. Bạn vẫn phải đọc lại test và chạy thử, vì agent có thể viết sai.

> Giao cho AI một việc thật, rồi giữ quyền kiểm tra từng bước: công cụ tốt là công cụ cho bạn đặt giới hạn.
>
> — Ông T

### Người dùng muốn theo dõi chi phí và tiến độ

Bạn sợ AI chạy lâu rồi tốn token mà không biết. Cài đường plugin, mở `/ruflo` để xem workflow, agent, model, token và chi phí cạnh Claude Code. 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ả: bạn nhìn được mình đang tốn gì thay vì đoán.

### Thử nghiệm để Claude điều khiển console, có giới hạn

README mô tả một bài thử an toàn. Vào console, chọn **Settings → Claude control → write + ask**, rồi nhờ:

```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. Bạn xác nhận hành động tạo trong console. Sau đó kiểm tra Missions có mục tiêu chưa và Overview có ghi lại hành động không. Mức mặc định hiện là **read + ask**. Bạn có thể bấm **Take back control** để dừng ngay. Lưu ý: tạo mission không có nghĩa tính năng đã được viết xong.

### Dev dùng Codex hoặc công cụ MCP khác

Bạn không dùng Claude Code mà dùng Codex. Thêm một MCP server với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Khi đó công cụ của ruflo sẵn sàng để Codex gọi. Nếu dùng Grok Build, README có lệnh `npx ruflo init --grok` và cờ `--dry-run` để xem trước những gì sẽ ghi.

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

**Báo lỗi hoặc không chạy được lệnh npx.** Thường do Node quá cũ hoặc chưa cài. Repo yêu cầu Node 20 trở lên. Chạy `node --version`, cập nhật Node rồi thử lại.

**Chạy init xong mà Claude Code không thấy gì.** Claude Code chỉ nhận cấu hình ở lần khởi động tiếp theo. Hãy đóng và mở lại Claude Code đúng thư mục bạn vừa chạy lệnh. Kiểm tra kỹ bạn không chạy lệnh ở thư mục khác.

**Lệnh /plugin không nhận hoặc cài plugin thất bại.** Đường plugin cần Claude Code 2.1.287 trở lên, còn lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code rồi thử lại, sau đó gõ `/reload-plugins`.

**Cài một plugin hai lần từ hai kho khác nhau.** README cảnh báo với các plugin ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`: chỉ cài từ một marketplace. Nếu bật từ cả hai, mod và lệnh sẽ nạp hai lần. Hãy gỡ một bản.

**Gọi tên công cụ MCP bị sai.** Với đường plugin, công cụ có dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, không phải `memory_store` trần như bản cài bằng CLI. Nếu hướng dẫn nào bảo dùng tên ngắn mà không chạy, hãy kiểm tra bạn đang dùng đường nào.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có đường cài "lite" không thêm file vào dự án. Hệ thống quyền của console khá chặt: mặc định read + ask, hành động liên quan mạng, chi tiêu hay phá huỷ vẫn phải xác nhận kể cả ở chế độ auto. Hệ sinh thái plugin rộng, giấy phép MIT, và repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Repo 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 người mới dễ choáng, dù tác giả khuyên cứ dùng Claude Code bình thường sau `init`. Bản cài đầy đủ thêm khá nhiều file vào dự án. Các mod không chạy trong sandbox. Chính README cũng nói các đoạn demo dùng dữ liệu mẫu và không chứng minh việc swarm hoàn thành công việc hay bộ nhớ gợi lại đúng. Hãy tự kiểm chứng bằng việc nhỏ trước.

**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 đơn giản trong một file, dùng Claude Code thuần là đủ. Nếu bạn không viết code, công cụ này chưa phải lựa chọn tự nhiên. Nếu chỉ muốn thử một tính năng, hãy cài đúng một plugin thay vì cả bộ.

## 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 bạn dùng và chỉnh sửa tự do. Tuy nhiên ruflo chạy trên Claude Code, Codex hoặc nhà cung cấp mô hình khác, và chi phí của các dịch vụ đó là chuyện riêng. README có plugin theo dõi token và ngân sách, còn chi tiết giá thì tư liệu chưa nói.

### Cần Node.js phiên bản nào?

File package.json của repo yêu cầu Node từ 20.0.0 trở lên. Bạn kiểm tra bằng lệnh node --version trước khi chạy npx ruflo@latest init.

### ruflo có chạy trên Windows không?

README mình có không nói rõ về hệ điều hành. Lệnh cài chỉ là npx nên về nguyên tắc cần Node 20 trở lên. Bạn nên xem thêm tài liệu trong thư mục docs của repo để chắc chắn.

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

Tư liệu không nêu yêu cầu GPU cho cách cài cơ bản. Một plugin trong danh sách (ruflo-ruvector) có nhắc tìm kiếm tăng tốc GPU, nhưng đó là tính năng riêng, không phải điều kiện bắt buộc theo README.

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

Có, nếu dùng npx ruflo@latest init. Lệnh này thêm file như .claude/, .claude-flow/, CLAUDE.md cùng các file hỗ trợ. Nếu không muốn thêm file, README có đường cài bằng plugin Claude Code, nhưng chức năng chỉ ở mức nhẹ hơn.

### Dùng ruflo có an toàn không?

README nói các mod chạy với quyền tài khoản của bạn và không nằm trong sandbox, nên cần đọc code trước khi cài. Console cho Claude điều khiển có mức quyền read, write, manage, full và mặc định là read + ask. Về chuyện dữ liệu gửi đi đâu, tư liệu mình có chưa nói đầy đủ.

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

Claude Code là công cụ chính để viết code. ruflo là lớp bọc ngoài, thêm agent chuyên biệt, swarm, bộ nhớ, hook và console theo dõi. Nó không thay Claude Code mà làm Claude Code phối hợp có tổ chức hơn.
