# ruflo: điều phối nhóm 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 mã nguồn mở giấy phép MIT, bọc quanh Claude Code và Codex để thêm agent chuyên biệt, bộ nhớ dài hạn, nhóm agent phối hợp và các lớp kiểm soát. Cài bằng một lệnh npx trong thư mục dự án, cần Node từ 20 trở lên. Cài không khó, nhưng repo rất lớn nên bạn nên bắt đầu từ một việc nhỏ.

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

ruflo là một **agent harness** (bộ khung bọc quanh mô hình AI) dành cho Claude Code và Codex. Mô hình AI viết code. Harness là phần còn lại: công cụ, bộ nhớ, vòng lặp làm việc và các lớp kiểm soát để AI làm được việc thật. Repo này trước đây có tên Claude Flow, tác giả là Reuven Cohen (rUv), viết bằng TypeScript, giấy phép MIT.

Nếu bạn đang dùng Claude Code và thấy mỗi lần mở phiên mới là AI "quên sạch", hoặc muốn nhiều agent cùng làm một việc (một agent tìm lỗi, một agent viết test, một agent tóm tắt), ruflo là thứ đáng thử. Người làm văn phòng hoặc kinh doanh không biết code vẫn có thể dùng, nhưng sẽ dễ hơn nếu bạn đã quen mở terminal và Claude Code.

Điểm đáng giá nhất là cách vào cửa: một lệnh `npx ruflo@latest init`, sau đó bạn cứ dùng Claude Code như bình thường. README nói bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Hiện repo có khoảng 81.582 sao và 9.607 fork, và vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) bọc quanh Claude Code và Codex: thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên, điều phối nhóm agent và bảng điều khiển.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README mô tả ruflo như một hệ thần kinh cho Claude Code. Dưới đây là những phần bạn sẽ thấy có ích nhất, giải thích theo lợi ích thực tế.

### Nhóm agent phối hợp (swarm)

ruflo thêm hơn 100 agent chuyên biệt và cho chúng làm việc theo nhóm. Bạn không phải giao từng việc nhỏ. Bạn chỉ cần nói "dùng một swarm của ruflo để rà soát repo này", rồi để các agent chia việc với nhau.

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

Ruflo có bộ nhớ tự học: agent nhớ được kinh nghiệm giữa các phiên làm việc và dùng lại khi định tuyến tác vụ. Phần truy xuất vector cục bộ và cập nhật đối chiếu có thể chạy mà không cần LLM, nhưng README lưu ý vẫn cần embedding và các module học đã được cấu hình. Nên đừng kỳ vọng "cắm vào là tự thông minh".

### Hooks chạy ngầm

Sau khi `init`, hệ thống hooks tự định tuyến tác vụ, học từ các mẫu thành công và điều phối agent ở phía sau. Bạn dùng Claude Code bình thường, không cần gõ lệnh riêng của ruflo.

### Bảng điều khiển ngay cạnh Claude Code

Plugin `ruflo-console` cho bạn theo dõi workflow, agent, model, token và chi phí. Bạn có thể mở log của từng agent, tìm kiếm, xem lại và so sánh các lần chạy. Gõ `/ruflo` trong Claude Code để mở.

### Cho Claude điều khiển bảng điều khiển, nhưng bạn giữ giới hạn

Trong Settings có mục Claude control với bốn mức: `read`, `write`, `manage`, `full`, kèm 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á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ả khi bạn để `auto`. Có nút **Take back control** để thu quyền lại ngay.

### Kho plugin lớn

README nói có 48 plugin (thêm 3 plugin bên ngoài), chia theo nhóm. Vài ví dụ dễ hiểu: `ruflo-swarm` (điều phối nhiều agent), `ruflo-testgen` (tìm test còn thiếu và tạo ra), `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí), `ruflo-security-audit` (quét lỗ hổng và CVE), `ruflo-docs` (tạo và duy trì tài liệu).

### Dùng được ngoài Claude Code

Codex và các MCP client khác cũng kết nối được tới máy chủ MCP của ruflo. Ngoài ra có giao diện terminal chạy riêng. README cũng nhắc tới federation (agent ở các máy khác nhau giao tiếp với nhau), nhưng đó là phần 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 rõ những điều sau, mình không thêm gì ngoài đó:

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json` của repo. Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn dùng cách cài bằng `init` hoặc bằng plugin. Riêng cách cài chỉ bằng plugin 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 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 `init`.

README phần mình có **không ghi** hệ điều hành cụ thể, yêu cầu GPU, hay API key bắt buộc. Nếu bạn cần biết những điều này, hãy xem thêm trong thư mục `docs/` của repo và file `README.md` đầy đủ.

```note
Các mod của ruflo chạy với đúng quyền tài khoản của bạn và không nằm trong sandbox. README khuyên bạn đọc code của mod trước khi cài. Cũng nên theo dõi chi phí token khi cho agent chạy tự động.
```

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

README có ba đường cài. Đường đầu tiên (dùng `init`) là đường chính, mình hướng dẫn kỹ nhất. Hai đường còn lại ở cuối phần này.

```steps
- Kiểm tra Node | Đảm bảo Node.js từ phiên bản 20 trở lên
- Mở terminal trong dự án | Vào đúng thư mục dự án bạn muốn dùng ruflo
- Chạy init | Chạy npx ruflo@latest init để thêm agent, hooks, bộ nhớ và máy chủ MCP
- 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 việc đầu tiên | Gõ một yêu cầu thật, hoặc gõ /ruflo để mở bảng điều khiển
```

### Kiểm tra Node.js

ruflo yêu cầu Node từ 20.0.0. Nếu bạn chưa chắc máy mình đang dùng bản nào, mở terminal và gõ:

```bash
node --version
```

Kết quả nên bắt đầu bằng v20 hoặc cao hơ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. README của ruflo không hướng dẫn phần này.

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

Đây là chỗ người mới hay vấp nhất. 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. Ví dụ với Windows PowerShell hoặc macOS/Linux:

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

Hãy thay `duong-dan-toi-du-an-cua-ban` bằng đường dẫn thật. Nếu bạn muốn xem mã nguồn của chính ruflo thay vì dùng nó trong dự án, bạn mới cần `git clone https://github.com/ruvnet/ruflo.git`. Với người dùng bình thường, bước này không cần.

### Chạy init

Đây là lệnh chính, chép nguyên từ README:

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

Lệnh này thêm agent, hooks, bộ nhớ và máy chủ MCP của ruflo vào dự án. Theo README, trong thư mục sẽ xuất hiện `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và settings. Vì vậy hãy chạy trong một dự án đã có Git, để bạn xem được những gì đã thay đổi và hoàn tác nếu muốn.

Nếu muốn cấu hình 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

Mở Claude Code trong **cùng thư mục**. README nói Claude Code sẽ nhận ra các thành phần mới ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn một phiên Claude Code từ trước, hãy thoát ra và mở lại.

### Giao việc đầu tiên

Bạn dán thẳng câu mẫu của README vào Claude Code:

```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 ruflo dùng một nhóm agent để rà soát dự án, tìm module rủi ro nhất, viết test cho nó và tóm tắt các thay đổi.

### Đường khác: chỉ cài plugin vào Claude Code

Cách này không thêm file nào vào dự án. README ghi nó cài công cụ lõi, bảng điều khiển và các mod, và cần Claude Code từ 2.1.287. 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, với Claude Code 2.1.292 trở lên, README ghi thêm lệnh này:

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

README so sánh hai đường như sau: cài plugin thì **không có file nào** trong dự án và không có hooks. Cài bằng `init` thì có đủ vòng lặp ruflo (98 agent, hơn 60 lệnh, 30 skill, máy chủ MCP, hooks, daemon). README khuyên dùng `init` cho việc nghiêm túc, và plugin cho người chỉ muốn thử vài lệnh.

### Đường khác: Codex hoặc MCP client khác

Không cần setup dự án. Bạn cấu hình trong client đó như sau: **command** là `npx`, **arguments** là danh sách dưới đây. Đây là cấu hình bạn điền vào client, README không cho biết file cấu hình của từng client nằm ở đâu.

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

Nếu client của bạn nhận một dòng lệnh duy nhất, đó là `npx -y ruflo@latest mcp start`.

## 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 bạn có thể dựa vào.

1. **Sau `init`:** trong thư mục dự án có `.claude/`, `.claude-flow/` và `CLAUDE.md`. Chạy `git status` để xem danh sách file mới.
2. **Sau khi mở lại Claude Code:** gõ `/ruflo`. README ghi đây là cách mở bảng điều khiển. Nếu bạn cài bằng plugin, mở `/plugin` để xem ruflo có nằm trong dòng các mod đang hoạt động hay không.
3. **Với plugin:** trong console, `/ruflo market` mở Plugin Catalog, liệt kê mọi plugin, mod và skill của ruflo, có nút cài, bật, tắt và cập nhật (mỗi thao tác đều hỏi trước).
4. **Giao diện terminal:** chạy `npx ruflo tui`. Nếu thấy màn hình bảng điều khiển hiện ra, ruflo chạy được độc lập với Claude Code.

```bash
npx ruflo tui
```

Thêm `--plain` nếu bạn chỉ muốn in ra một khung hình dùng cho script.

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

README mô tả ruflo gọn trong một câu mà mình thấy đúng tinh thần:

> Bạn vẫn viết code. ruflo lo phần điều phối.
>
> — Ông T

Dưới đây là bốn tình huống bám sát những gì README nêu.

### Lập trình viên rà soát một dự án thừa kế

Bạn nhận một dự án của người khác, không biết chỗ nào dễ hỏng. Sau khi `init` và khởi động lại Claude Code, bạn 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.
```

Kết quả mong đợi: các agent tìm module rủi ro nhất, viết test cho nó, và cuối cùng bạn nhận một bản tóm tắt những gì đã thay đổi. Đọc kỹ bản tóm tắt và xem `git diff` trước khi giữ lại thay đổi nào.

### Chủ dự án muốn nhìn thấy AI đang làm gì

Bạn không muốn AI chạy trong "hộp đen". Mở `/ruflo`, vào **Settings → Claude control**, chọn **write + ask**. Rồi bảo Claude:

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

Claude mở trang Missions và đặt mục tiêu, bạn xác nhận hành động tạo đang chờ. Sau đó kiểm tra mục 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 là tính năng đã được làm xong**. Muốn dừng, bấm **Take back control**; lần gọi tiếp theo của Claude sẽ bị từ chối cho tới khi bạn trả quyền lại.

### Người dùng Codex hoặc công cụ khác chỉ muốn thêm trí nhớ và công cụ

Bạn không dùng Claude Code. Trong client MCP của mình, bạn khai báo command `npx` với các đối số `-y`, `ruflo@latest`, `mcp`, `start`. Client sẽ gọi được các công cụ MCP của ruflo mà không cần thay đổi gì trong dự án. Nếu muốn có hướng dẫn tương tác, chạy `npx ruflo@latest init wizard`.

### Người mới muốn thử nhẹ, không đụng vào dự án

Bạn chưa muốn thêm file vào dự án. Hãy cài theo đường plugin. Ngoài `ruflo-core`, bạn có thể thêm từng plugin theo nhu cầu, ví dụ `ruflo-swarm` để điều phối nhiều agent, hoặc `ruflo-testgen` để tìm test còn thiếu:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
```

Cách này chỉ cho lệnh gạch chéo và định nghĩa agent. Bạn không có hooks. Nếu muốn trải nghiệm đầy đủ như README mô tả, bạn vẫn cần `init`.

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

### Lệnh npx báo lỗi hoặc không chạy được

Nguyên nhân thường gặp là Node cũ hơn 20, vì `package.json` của repo yêu cầu từ 20.0.0. Hãy chạy `node --version`. Nếu thấp hơn, nâng cấp Node rồi chạy lại. Nếu vẫn lỗi, xem mục issues trên trang GitHub của repo.

### Chạy `init` xong mà Claude Code không thấy gì

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 phiên cũ và mở lại **trong đúng thư mục** bạn đã chạy `init`. Nếu mở ở thư mục khác, Claude Code sẽ không thấy `.claude/` của dự án.

### Lệnh `/plugin install` không nhận hoặc báo lỗi

Cách cài plugin cần Claude Code từ 2.1.287, và lệnh `claude plugin install` ở terminal cần từ 2.1.292. Hãy cập nhật Claude Code trước. Sau khi cài xong, nhớ chạy `/reload-plugins`.

### Plugin chạy hai lần hoặc trùng lệnh

Với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb` và `agentic-flow`, README cảnh báo: chỉ cài từ **một** marketplace. Nếu bật từ cả hai nơi, mod và lệnh sẽ được nạp hai lần. Ngoài ra, plugin bên ngoài do nhóm khác duy trì, nên hãy đọc kỹ trang của họ.

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

Đây là hành vi thiết kế, không phải lỗi. Mức mặc định là read + ask, nên hành động ghi hoặc quản lý sẽ bị từ chối. Nếu bạn thật sự muốn Claude làm, hãy nâng mức lên `write` rồi vẫn để `ask` để tự duyệt. Hành động liên quan mạng, chi tiêu, phá huỷ luôn cần bạn xác nhận.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có sẵn lượng lớn agent, plugin và công cụ nên bạn không phải tự dựng. Bộ nhớ qua phiên và nhóm agent giúp xử lý việc dài hơi. Bảng điều khiển cho bạn nhìn thấy agent đang làm gì, tốn bao nhiêu token. Cơ chế quyền (read, write, manage, full) và nút lấy lại quyền kiểm soát là điểm cộng lớn về an toàn. Giấy phép MIT, nên dùng và sửa thoải mái.

**Giới hạn.** Repo rất lớn: hàng chục plugin, hàng trăm công cụ MCP, nhiều khái niệm (swarm, federation, vector RAG). Người mới dễ choáng. `init` thêm khá nhiều file vào dự án. Phần bộ nhớ và học vẫn cần embedding và module được cấu hình, nên đừng mong nó tự hoàn hảo. Các mod không chạy trong sandbox và dùng quyền tài khoản của bạn. README cũng nói rõ bản ghi hình và hoạt ảnh demo không chứng minh việc swarm đã hoàn thành công việc hay bộ nhớ nhớ lại được thông tin.

**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ỏ, cứ dùng Claude Code bình thường là đủ, chưa cần thêm một lớp harness. Nếu bạn chưa quen terminal hoặc Git, hãy thử đường plugin trước, không ghi file vào dự án. Với công việc quan trọng, hãy chạy trên một dự án đã có Git, bắt đầu từ một việc nhỏ như câu mẫu rà soát repo, rồi mới mở rộng dần.

## 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 được dùng và sửa mã nguồn. Tuy nhiên tư liệu không nói gì về chi phí của các mô hình AI hay dịch vụ đi kèm. Khi cho agent chạy, bạn vẫn dùng tài khoản và hạn mức của Claude Code hoặc Codex của chính bạn, nên cần theo dõi chi phí token.

### ruflo là gì, khác gì Claude Code?

Claude Code là công cụ AI viết code. ruflo là lớp harness bọc quanh nó, thêm agent chuyên biệt, bộ nhớ qua các phiên, điều phối nhóm agent, hooks và bảng điều khiển. Bạn vẫn dùng Claude Code như bình thường, ruflo chạy ngầm phía sau.

### Cài ruflo cần những gì?

Theo package.json, bạn cần Node.js từ 20.0.0 trở lên. Nếu cài bằng plugin, cần Claude Code từ 2.1.287. Tư liệu không nêu yêu cầu GPU hay API key bắt buộc.

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

README phần mình có không nêu rõ hệ điều hành nào được hỗ trợ. Chưa có thông tin chắc chắn về Windows, bạn nên xem README đầy đủ và thư mục docs của repo, hoặc mục issues trước khi cài.

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

Được. README ghi Codex và các MCP client khác dùng được: cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Bạn cũng có thể chạy giao diện terminal riêng bằng npx ruflo tui.

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

README nêu các lớp kiểm soát: bốn mức quyền (read, write, manage, full), chế độ duyệt ask hoặc auto, mặc định là read + ask. Hành động vượt quyền bị từ chối, hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận. Bạn có thể bấm Take back control để dừng. Riêng các mod thì không chạy trong sandbox, nên cần đọc code trước khi cài.

### Nên cài bằng init hay bằng plugin?

Cài bằng npx ruflo@latest init cho bạn vòng lặp đầy đủ (agent, lệnh, skill, máy chủ MCP, hooks, daemon) nhưng thêm file vào dự án. Cài bằng plugin thì không thêm file nào, nhưng chỉ có lệnh gạch chéo và định nghĩa agent, không có hooks. README khuyên dùng init cho việc nghiêm túc.
