# 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: lớp công cụ bao quanh Claude Code và Codex, thêm agent, hook, bộ nhớ và máy chủ MCP. Bạn dùng nó để giao việc lớn cho cả nhóm agent phối hợp thay vì một agent đơn lẻ. Cài khá dễ: 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-05-17 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-ai-claude-code-codex-huong-dan-16

ruflo là một "agent harness" mã nguồn mở, bao quanh Claude Code và Codex. Hiểu đơn giản: mô hình AI là người viết, còn harness là cái bàn làm việc đầy đủ đồ nghề (công cụ, bộ nhớ, vòng lặp kiểm tra, giới hạn an toàn) để người viết đó làm việc thật. ruflo chính là cái bàn đó. Repo này trước đây tên Claude Flow, hiện có khoảng 81.600 sao và 9.600 fork trên GitHub, giấy phép MIT.

Vấn đề nó giải quyết: dùng Claude Code một mình thì mỗi phiên làm việc khá "trắng", không nhớ gì từ lần trước và không tự chia việc cho nhiều agent. ruflo thêm hơn 100 agent chuyên biệt, các nhóm agent (swarm) phối hợp, bộ nhớ giữ qua nhiều phiên và máy chủ MCP. Sau khi cài, bạn vẫn dùng Claude Code như bình thường, phần điều phối chạy nền.

Ai nên dùng? Lập trình viên đã dùng Claude Code hoặc Codex và muốn giao việc dài hơi như rà soát repo, viết test, ghi nhớ quy ước dự án. Người làm kinh doanh hoặc văn phòng cũng thử được, nhưng nên có người biết dùng terminal ngồi cạnh ở lần đầu. Điểm đáng giá nhất: một lệnh `npx` là xong phần cài, và có bảng điều khiển ngay trong Claude Code để xem agent đang làm gì, tốn bao nhiêu token.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) bao quanh Claude Code và Codex, thêm agent chuyên biệt, nhóm agent phối hợp, bộ nhớ dài hạn và bảng điều khiển theo dõi chi phí.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Tư liệu của repo khá dày. Dưới đây là những phần đáng quan tâm nhất với người mới.

**Nhóm agent phối hợp (swarm).** Thay vì một agent làm tuần tự, bạn có thể ra lệnh "dùng một swarm để làm việc X". Các agent chia nhau việc rồi gộp kết quả. README mô tả hơn 100 agent chuyên biệt; bảng so sánh cách cài ghi 98 agent trong bản cài bằng CLI.

**Bộ nhớ qua nhiều phiên.** Agent có thể lưu và tìm lại kinh nghiệm cũ, có tìm kiếm vector. Lợi ích thực tế: lần sau giao việc tương tự, agent không phải bắt đầu từ con số không. README cũng nói rõ phần học này là "mô hình khái niệm", một số phần vẫn cần cấu hình embedding.

**Hook tự định tuyến.** Sau khi cài, hệ thống hook tự chọn agent phù hợp cho từng tác vụ và học từ những lần làm tốt. README nhấn mạnh 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ảng điều khiển (console).** Một "buồng lái" cạnh Claude Code: theo dõi quy trình, agent, mô hình, token và chi phí; mở log để xem lại, tìm kiếm, tìm lỗi. Bạn mở nó bằng lệnh `/ruflo` trong Claude Code.

**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 bốn mức quyền: `read`, `write`, `manage`, `full`, và hai chế độ duyệt: `ask` (hỏi bạn) hoặc `auto`. Mặc định hiện là read + ask. Hành động liên quan mạng, tiền hoặc xoá phá hủy vẫn phải được xác nhận, kể cả ở chế độ `auto`.

**Hệ plugin lớn.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), tạo test (testgen), quét bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker)... Bạn chỉ cài cái cần dùng.

**Liên kết nhiều máy (federation).** Agent trên các máy khác nhau có thể phối hợp 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ừ 20.0.0 trở lên** (theo `package.json`), vì lệnh cài chạy qua `npx`.
- **Claude Code** đã cài trên máy, vì ruflo bổ sung vào Claude Code. Nếu bạn đi đường cài plugin thì cần Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` từ terminal cần **2.1.292 trở lên**.
- **Codex hoặc client MCP khác** nếu bạn không dùng Claude Code. Cách nối nằm ở phần cài đặt bên dưới.
- Một thư mục dự án để chạy lệnh `init`.

Về API key, tài khoản trả phí hay phần cứng (GPU): phần README mình đọc được chưa nói gì. Phần "học cục bộ" có nhắc cần embedding và các module học được cấu hình. Chi tiết xem thêm trong README đầy đủ và thư mục `docs/` của repo.

```note
Một số mod của ruflo chạy với đúng quyền tài khoản của bạn và không bị sandbox. README dặn: hãy đọc code trước khi cài. Ngoài ra, thao tác cài đặt sẽ thêm file vào dự án, nên thử trên một dự án có sao lưu hoặc có git trước.
```

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

README đưa ra vài đường cài. Đường nhanh và đầy đủ nhất là `npx ruflo@latest init`. Mình làm theo đường này trước, rồi nói các cách khác.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án của bạn
- Chạy lệnh init | Thêm agent, hook, bộ nhớ và máy chủ MCP vào dự án
- Mở lại Claude Code | Claude Code nạp ruflo ở lần khởi động kế tiếp
- Giao một việc thật | Dùng câu lệnh mẫu để thử swarm
- Mở bảng điều khiển | Gõ /ruflo để xem agent và chi phí
```

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

Lệnh `init` ghi file vào nơi bạn đang đứng, nên phải đứng đúng thư mục dự án. Trên Windows, bạn có thể mở thư mục trong Explorer, gõ `powershell` vào thanh địa chỉ rồi Enter. Hoặc dùng `cd` như dưới đây (thay đường dẫn bằng thư mục của bạn):

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

Nếu bạn muốn tải cả mã nguồn ruflo về xem, lệnh phổ thông là:

```bash
git clone https://github.com/ruvnet/ruflo.git
```

Việc này không bắt buộc để dùng. Cài qua `npx` không cần clone.

### Chạy lệnh init

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

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

`npx` tải ruflo bản mới nhất rồi chạy, không cần cài toàn cục. Lệnh `init` thêm agent, hook, bộ nhớ và máy chủ MCP của ruflo vào dự án. Theo bảng so sánh trong README, bản cài này tạo các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md` và file cài đặt trong dự án. Nếu bạn 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
```

Chỗ người mới hay vấp: nếu báo lỗi phiên bản Node, hãy kiểm tra Node đã từ 20 trở lên chưa (xem phần lỗi bên dưới).

### Mở lại Claude Code trong cùng thư mục

README nói Claude Code sẽ nhận ruflo ở lần khởi động kế tiếp. Vậy hãy thoát Claude Code nếu đang mở, rồi mở lại trong chính thư mục vừa chạy `init`. Mở ở thư mục khác thì sẽ không thấy gì.

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

Ngay trong Claude Code, gõ câu lệnh 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ờ một swarm rà soát repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn có thể dịch sang tiếng Việt nếu muốn, nhưng mình giữ nguyên bản tiếng Anh theo README cho chắc.

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

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

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

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

So sánh nhanh theo README: đường plugin cho "lite", không thêm file vào dự án, không cài hook; đường `npx ruflo@latest init` cho vòng làm việc đầy đủ gồm hook, MCP server, daemon, và là đường được khuyên cho dùng thật.

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

Với Codex hay client MCP không cần thiết lập dự án, README bảo cấu hình **command** là `npx` và **arguments** là:

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

Tương đương dòng lệnh:

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

Cách điền vào giao diện cấu hình MCP phụ thuộc từng client, bạn xem tài liệu client đó.

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

Bảng điều khiển có thể chạy riêng, không cần Claude Code:

```bash
npx ruflo tui
```

Thêm `--plain` để in một khung hình duy nhất, tiện cho script.

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

Có ba cách để biết cài thành công, đều theo README:

1. **Sau `init`**: mở lại Claude Code trong thư mục dự án. Trong thư mục sẽ có các mục như `.claude/`, `.claude-flow/` và `CLAUDE.md` do ruflo tạo.
2. **Gõ `/ruflo` trong Claude Code**: bảng điều khiển mở ra. Đây là dấu hiệu rõ nhất là console đã chạy.
3. **Gõ `/plugin`** nếu bạn đi đường plugin: các mod ruflo phải hiện trong dòng "active mods".

Nếu cài bằng plugin mà lệnh chưa nhận, chạy `/reload-plugins` rồi thử lại. Với đường `npx ruflo tui`, bạn sẽ thấy giao diện bảng điều khiển ngay trong terminal.

Lưu ý thật thà từ chính README: các đoạn demo hoạt hình của repo dùng dữ liệu mẫu, nên đừng coi chúng là bằng chứng swarm đã làm xong việc. Bằng chứng của bạn là kết quả thật trong dự án của bạn.

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

Các tình huống dưới đây bám đúng những gì README mô tả. Kết quả cụ thể sẽ khác tuỳ dự án và mô hình bạn dùng.

### Lập trình viên: rà soát một repo và viết test cho chỗ rủi ro

Bạn nhận lại một dự án cũ, không ai nhớ phần nào dễ hỏng. Sau khi chạy `npx ruflo@latest init` và mở lại Claude Code, bạn giao đúng 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.
```

Swarm chia việc: tìm module rủi ro nhất, viết test, rồi tóm tắt. Bạn nhận một bản tóm tắt thay đổi và các file test mới để tự xem lại trước khi giữ. Nên chạy trên nhánh git riêng để dễ bỏ nếu không ưng.

> Mô hình chỉ là người viết. Cái bàn làm việc quanh nó mới quyết định việc có xong và có kiểm chứng được hay không.
>
> — Ông T

### Người quản lý dự án: giao việc qua bảng điều khiển, giữ quyền duyệt

Bạn muốn thử xem Claude thao tác trên console có an toàn không. Làm theo luồng README mô tả:

1. Cài console bằng các lệnh `/plugin` ở phần trên, mở `/ruflo`.
2. Chọn **Settings → Claude control → write + ask**.
3. Nhờ Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status."
4. Xác nhận hành động tạo khi console hỏi.
5. Kiểm tra mục Missions đã có mục tiêu và Overview đã ghi lại hành động.

Kết quả: bạn có một "mission" được tạo, với mọi thao tác ghi log. README nhắc rõ tạo mission không có nghĩa tính năng đã được làm ra. Nếu muốn dừng, bấm **Take back control** và mọi lời gọi tiếp theo của Claude vào console sẽ bị từ chối cho đến khi bạn cấp lại quyền.

### Người dùng Codex hoặc công cụ MCP khác

Bạn không dùng Claude Code mà dùng Codex. Bạn cấu hình máy chủ MCP với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Nhờ vậy client của bạn gọi được các công cụ của ruflo (bộ nhớ, điều phối agent) mà không cần thêm file vào dự án. Kết quả mong đợi: công cụ ruflo xuất hiện trong danh sách công cụ MCP của client. Cách hiển thị tuỳ từng phần mềm.

### Người cần theo dõi chi phí hoặc kiểm soát tự động hoá

Bạn lo chạy agent lâu sẽ tốn token. Console có phần theo dõi token và chi phí cạnh Claude Code. Ngoài ra, README liệt kê plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, báo động chi phí) và `ruflo-protector` (giám sát agent chạy không người trông). Chúng cài theo cùng kiểu `/plugin install <tên>@ruflo` như các plugin ở trên. Kết quả: bạn nhìn được mức tiêu thụ thay vì đoán mò. Cách đặt ngân sách chi tiết, xem tài liệu của plugin trong repo.

## 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 cũ. `package.json` yêu cầu Node từ 20.0.0. Kiểm tra bằng `node --version`, nếu thấp hơn thì cập nhật Node rồi chạy lại. Nếu máy chưa có Node, bạn cài Node trước.

### Mở Claude Code nhưng không thấy ruflo

Có hai nguyên nhân hay gặp. Một là bạn chưa khởi động lại Claude Code sau `init`. Hai là bạn mở Claude Code ở thư mục khác với nơi chạy `init`. Hãy thoát hẳn, vào đúng thư mục, mở lại. Nếu đi đường plugin, chạy `/reload-plugins` rồi `/plugin` để xem mod đã hiện chưa.

### Lệnh `/plugin` không nhận hoặc cài plugin thất bại

Đường plugin cần Claude Code từ 2.1.287, còn lệnh `claude plugin install` từ terminal cần 2.1.292. Nếu Claude Code của bạn cũ hơn, hãy cập nhật Claude Code trước, hoặc quay về đường `npx ruflo@latest init`.

### Thư mục dự án bỗng có nhiều file lạ

Đó là bình thường với đường `init`: nó thêm `.claude/`, `.claude-flow/`, `CLAUDE.md` và các file phụ trợ. Nếu bạn không muốn đụng dự án chính, thử trên bản sao hoặc nhánh git riêng. Hoặc dùng đường plugin, vốn không thêm file nào vào dự án.

### Plugin chạy hai lần, lệnh bị trùng

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, nếu bật từ cả hai nơi thì mod và lệnh bị nạp hai lần. Hãy gỡ một bản rồi giữ bản còn lại.

### Claude bị từ chối khi điều khiển console

Đây là hành vi thiết kế, không phải lỗi. Mặc định là read + ask, nên các hành động vượt quyền sẽ bị từ chối. Muốn Claude tạo hay sửa, bạn nâng mức quyền trong Settings → Claude control, nhưng hãy giữ chế độ `ask` để tự duyệt từng thao tác.

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

**Điểm mạnh.** Cài chỉ một lệnh. Có sẵn nhiều agent, bộ nhớ, bảng điều khiển và hệ plugin lớn. Nối được với cả Claude Code lẫn Codex. Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây. Cơ chế quyền của console (mặc định chỉ đọc và hỏi lại) cho thấy tác giả chú ý đến an toàn.

**Giới hạn.** Bộ công cụ rất lớn (hàng trăm công cụ MCP, hàng chục lệnh, 48 plugin), nên người mới dễ choáng. Bạn nên bắt đầu với một việc nhỏ, đừng bật hết. Bản cài đầy đủ thêm 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 bị sandbox. README cũng thẳng thắn rằng một số phần minh hoạ dùng dữ liệu mẫu và phần học cục bộ vẫn cần cấu hình embedding. Còn chi phí token khi chạy nhiều agent cùng lúc, tư liệu mình đọc chưa đưa con số nào, bạn nên theo dõi trong console.

**Khi nên chọn cách khác.** Nếu việc của bạn là một vài thao tác đơn giản như sửa một file hay hỏi đáp về code, dùng Claude Code hoặc Codex nguyên bản là đủ, không cần thêm tầng điều phối. Nếu bạn chỉ muốn thử một chức năng, đường plugin nhẹ hơn. ruflo đáng thử khi bạn đã quen Claude Code và muốn giao việc lớn, nhiều bước, cần ghi nhớ và có chỗ theo dõi.

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

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

Mã nguồn ruflo theo giấy phép MIT, nên dùng và sửa tự do. Tuy vậy, ruflo chạy trên Claude Code hoặc Codex, nên chi phí dùng các mô hình đó vẫn tính riêng theo gói của bạn. Tư liệu mình đọc chưa nêu mức giá cụ thể.

### Cần GPU hay máy mạnh không?

Tư liệu mình đọc không yêu cầu GPU cho cách cài cơ bản, chỉ cần Node 20 trở lên. Một số plugin như ruflo-ruvector nhắc đến tìm kiếm tăng tốc GPU, nhưng đó là tuỳ chọn. Yêu cầu phần cứng chi tiết chưa có trong phần README mình đọc.

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

Cách cài chính chỉ là lệnh npx, chạy qua Node.js. README phần mình đọc không liệt kê hệ điều hành được hỗ trợ hay không được hỗ trợ. Nếu bạn gặp lỗi riêng trên Windows, hãy xem mục issues và thư mục docs của repo.

### Cài bằng npx init khác gì cài bằng plugin?

Theo README, plugin là bản nhẹ: có lệnh slash và vài skill, không thêm file vào dự án và không cài hook. Còn `npx ruflo@latest init` cho vòng làm việc đầy đủ gồm 98 agent, hơn 60 lệnh, 30 skill, máy chủ MCP, hook và daemon, và được khuyên dùng cho việc thật.

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

Được. README nói Codex và các client MCP khác dùng được: bạn cấu hình command là npx với các tham số -y, ruflo@latest, mcp, start. Cách điền vào từng client cụ thể thì tuỳ phần mềm đó.

### Để Claude điều khiển bảng điều khiển có an toàn không?

Mặc định là read + ask, tức chỉ đọc và hỏi bạn trước. Bạn có thể nâng lên write, manage hoặc full, còn hành động liên quan mạng, chi tiêu và xoá phá hủy vẫn cần xác nhận kể cả ở chế độ auto. Có nhật ký thao tác trực tiếp và nút Take back control để dừng ngay.

### Dữ liệu của mình có bị gửi đi đâu không?

Phần README mình đọc chưa nói chi tiết về luồng dữ liệu. Có nhắc rằng phần học cục bộ và truy xuất vector chạy được mà không cần LLM, và tính năng federation hướng tới việc trao đổi giữa các máy mà không rò rỉ dữ liệu. Nếu dự án của bạn nhạy cảm, hãy đọc SECURITY.md và tài liệu trong repo trước khi dùng.
