# Ruflo: điều phối nhóm 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 "harness" cho Claude Code và Codex: nó thêm agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên làm việc và hệ thống hook. Bạn cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node từ bản 20 trở lên. Với người đã dùng Claude Code thì 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-09-20 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-claude-code-codex-huong-dan

Ruflo là một "harness" (bộ khung làm việc) bao quanh Claude Code và Codex. Hiểu đơn giản: mô hình AI lo phần viết, còn Ruflo lo phần còn lại, gồm công cụ, bộ nhớ, vòng lặp, kiểm soát và việc chia việc cho nhiều agent. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, giấy phép MIT.

Vấn đề nó giải quyết rất quen thuộc. Khi bạn giao Claude Code một việc lớn, nó làm tuần tự, quên bối cảnh giữa các phiên và không có ai kiểm tra chéo. Ruflo thêm lớp điều phối: nhiều agent chuyên biệt làm song song, có bộ nhớ để lần sau không phải giải thích lại, và có hook tự chọn cách xử lý phù hợp cho từng tác vụ.

Ai nên đọc bài này? Lập trình viên mới đã dùng Claude Code và muốn nâng cấp cách làm việc. Người làm kinh doanh, văn phòng có người hỗ trợ kỹ thuật cũng đọc được, vì phần cài chỉ một lệnh. Điểm đáng giá nhất: README nói bạn không cần học hết các công cụ. Sau khi chạy `init`, bạn cứ dùng Claude Code như bình thường, phần còn lại chạy ngầm.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung bao quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ và hook. Cài bằng một lệnh npx trong thư mục dự án.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README giới thiệu rất nhiều thứ. Mình gom lại thành những ý có lợi ích thực tế nhất.

- **Agent chuyên biệt và swarm.** Thay vì một AI làm tất cả, Ruflo cung cấp hàng chục agent theo vai trò (README ghi 98 agent ở đường cài bằng CLI) và cho chúng phối hợp thành "swarm", tức một nhóm cùng làm một việc. Bạn nhận được kết quả từ cả nhóm, không phải từ một người.
- **Hook tự định tuyến.** Sau `init`, hệ thống hook tự chuyển tác vụ đến đúng chỗ, học từ những lần làm thành công và phối hợp agent ở nền. Bạn không phải nhớ lệnh nào.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ kinh nghiệm giữa các lần làm việc. README mô tả quá trình học là một vòng lặp mang tính khái niệm, và nói rõ việc truy xuất vector cục bộ có thể chạy không cần LLM, nhưng vẫn cần embeddings và các module học đã cấu hình.
- **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 một cách an toàn, theo README là không làm rò rỉ dữ liệu.
- **Bảng điều khiển `/ruflo`.** Một "buồng lái" nằm cạnh Claude Code, cho bạn theo dõi quy trình, agent, mô hình, token và chi phí. Bạn mở nhật ký từng lần chạy, tìm kiếm, xem lại và 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, mục Claude control có 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 mạng, tốn tiền hoặc phá huỷ vẫn phải xác nhận ngay cả khi để `auto`.
- **Kho plugin lớn.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia nhóm như điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, theo dõi chi phí. Bạn chỉ cài cái cần.
- **Chạy được với Codex và các client MCP khác.** Không bắt buộc dùng Claude Code.

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

Tư liệu ghi những điều sau:

- **Node.js bản 20.0.0 trở lên.** Đây là yêu cầu trong `package.json`. Lệnh `npx` đi kèm Node nên bạn không cần cài gì thêm.
- **Claude Code**, nếu bạn đi đường cài plugin. Cần bản **2.1.287 trở lên** cho lệnh trong Claude Code, và **2.1.292 trở lên** nếu muốn cài plugin từ terminal bằng `claude plugin install`.
- **Một thư mục dự án** để chạy `init`. Lệnh này thêm file vào chính thư mục đó.
- **Codex hoặc client MCP khác**, chỉ khi bạn muốn dùng thay Claude Code.

README phần đầu **chưa nêu** hệ điều hành cụ thể, yêu cầu phần cứng hay API key riêng cho Ruflo. Tài khoản và quyền truy cập mô hình chính là của công cụ bạn đang dùng (Claude Code hoặc Codex). Nếu bạn dùng các plugin phụ như chạy mô hình cục bộ, hãy xem trang riêng của plugin đó trong repo.

```note
Các "mod" cài từ kho plugin của Ruflo chạy với quyền tài khoản của bạn và không bị cô lập (sandbox). README khuyên đọc mã nguồn trước khi cài. Với máy làm việc quan trọng, hãy thử trên một thư mục dự án thử nghiệm trước.
```

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

README đưa ra một đường chính và vài đường phụ. Đường chính chỉ cần một lệnh.

```steps
- Mở terminal đúng chỗ | Vào thư mục dự án mà bạn muốn dùng Ruflo
- Chạy init | Dùng npx ruflo@latest init để thêm agent, hook, bộ nhớ và MCP server
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nạp cấu hình mới
- Giao việc đầu tiên | Gõ một yêu cầu thật, ví dụ nhờ swarm rà soát repo
- Tuỳ chọn | Cài plugin, nối Codex qua MCP hoặc mở giao diện terminal
```

### Mở terminal trong 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 thư mục dự án. Trên Windows, bạn có thể mở thư mục trong File Explorer, gõ `powershell` lên thanh địa chỉ rồi Enter. Nếu chưa có dự án, tạo một thư mục thử cho an toàn.

```bash
cd ten-thu-muc-du-an
```

Thay `ten-thu-muc-du-an` bằng đường dẫn thư mục của bạn.

### Chạy lệnh init

Lệnh này đúng nguyên văn trong README:

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

`npx` tải và chạy Ruflo bản mới nhất mà không cần cài toàn cục. Theo README, `init` thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Bảng so sánh trong README cho biết đường này tạo các thư mục `.claude/`, `.claude-flow/`, file `CLAUDE.md` cùng một số file hỗ trợ và settings. Lần chạy đầu có thể chậm hơn vì phải tải về.

Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh riêng:

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

### Mở lại Claude Code

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

### Đường phụ 1: chỉ cài plugin trong Claude Code

Đường này không thêm file nào vào dự án. Nó cài công cụ cốt lõi, bảng điều khiển và các mod. Gõ từng dòng sau **bên trong Claude Code** (không phải trong 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
```

Nếu dùng Claude Code bản 2.1.292 trở lên, bạn cũng có thể cài từ terminal:

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

README lưu ý đường plugin là bản "lite": chủ yếu có lệnh gạch chéo và định nghĩa agent. Muốn đủ bộ (hook, daemon, MCP server theo tên công cụ chuẩn) thì dùng đường `init`.

### Đường phụ 2: nối Codex hoặc client MCP khác

Với Codex hoặc client MCP bất kỳ, bạn không cần thiết lập dự án. Trong phần cấu hình MCP của client đó, điền **command** là `npx` và **arguments** như sau:

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

README cũng viết gọn thành lệnh `npx -y ruflo@latest mcp start`. Cách điền cụ thể vào từng client thì README phần đầu chưa hướng dẫn, bạn xem tài liệu của client đó.

### Đường phụ 3: giao diện terminal riêng

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

```bash
npx ruflo tui
```

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

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

README không đưa ra một dòng "thành công" cố định, nhưng có vài dấu hiệu rõ ràng để bạn tự kiểm:

- **Sau `init`:** trong thư mục dự án xuất hiện `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- **Sau khi mở lại Claude Code:** gõ `/ruflo` và bảng điều khiển hiện ra. README dặn thứ tự là `npx ruflo init`, khởi động lại Claude Code, rồi `/ruflo`.
- **Với đường plugin:** gõ `/plugin` và kiểm tra các mod bạn vừa cài có trong dòng "active mods".
- **Với giao diện terminal:** `npx ruflo tui` hiện khung giao diện.
- **Thử bằng một việc thật:** giao một tác vụ nhỏ cho Claude Code (xem phần tiếp theo) và xem bảng điều khiển có ghi lại hoạt động.

Nếu một trong các bước trên không ra kết quả, xem phần lỗi hay gặp ở dưới.

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

Dưới đây là các tình huống bám sát những gì README mô tả.

### Rà soát một dự án cũ như một nhóm

Bối cảnh: bạn là lập trình viên mới nhận lại một dự án không có tài liệu, và chưa biết chỗ nào dễ hỏng. Sau khi chạy `init` và mở lại Claude Code, bạn gõ đúng câu README gợi ý:

```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 những gì đã đổi. Kết quả bạn nhận được là một bản tóm tắt thay đổi cùng bộ test mới. Hãy đọc lại test và các thay đổi trước khi giữ, vì AI vẫn có thể sai.

> Agent = Model + Harness. Mô hình viết, còn bộ khung mới là thứ giúp nó thật sự làm việc.
>
> — Ông T

### Quan sát và giữ quyền kiểm soát bằng bảng điều khiển

Bối cảnh: bạn là trưởng nhóm, muốn biết agent đang làm gì và tốn bao nhiêu token. Cài `ruflo-console` rồi mở `/ruflo`. Bảng điều khiển cho bạn xem quy trình, agent, mô hình, token và chi phí, mở nhật ký từng lần chạy, tìm kiếm và so sánh các lần chạy.

Nếu muốn Claude thao tác trong bảng điều khiển, README có kịch bản thử an toàn: vào Settings, chọn Claude control, đặt **write + ask**. Rồi yêu cầu:

```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. Kết quả: mục tiêu xuất hiện trong Missions và Overview ghi lại hành động. README nhấn mạnh tạo mission **không có nghĩa** tính năng đã được làm. Muốn dừng, bấm **Take back control**.

### Dùng Ruflo từ Codex hoặc client MCP khác

Bối cảnh: nhóm bạn dùng Codex thay vì Claude Code. Bạn cấu hình MCP server với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Khi đó các công cụ của Ruflo hiện ra trong client đó. Bạn không cần chạy `init` cho dự án. Kết quả là cùng một bộ công cụ điều phối được dùng chung giữa nhiều client.

### Chọn đúng plugin cho việc nhỏ

Bối cảnh: bạn chưa muốn thêm file vào dự án, chỉ muốn thử vài tính năng. Đi đường plugin: cài `ruflo-core`, rồi thêm plugin hợp việc. Trong bảng README có `ruflo-testgen` (tìm test còn thiếu và tạo tự động), `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí) và `ruflo-docs` (tạo và duy trì tài liệu). Cú pháp cài giống các lệnh ở trên, ví dụ `/plugin install ruflo-testgen@ruflo`. Kết quả: bạn chỉ nhận đúng tính năng cần, không kéo theo cả bộ.

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

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

Nguyên nhân dễ gặp nhất là Node quá cũ, vì Ruflo yêu cầu bản 20.0.0 trở lên. Kiểm tra bằng:

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 20, hãy cập nhật Node từ trang chính thức rồi chạy lại. Lệnh `init` chỉ ghi vào dự án hiện tại nên chạy lại là an toàn về mặt vị trí, miễn bạn đứng đúng thư mục.

### Claude Code không thấy gì sau khi init

Hầu như luôn do chưa khởi động lại. README ghi Claude Code nhận cấu hình ở lần khởi động kế tiếp. Thoát hẳn, mở lại **trong đúng thư mục** đã chạy `init`, rồi gõ `/ruflo`.

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

Đường plugin cần Claude Code từ bản 2.1.287 trở lên (và 2.1.292 trở lên cho lệnh `claude plugin install` ở terminal). Hãy cập nhật Claude Code. Sau khi cài xong nhớ chạy `/reload-plugins`, rồi mở `/plugin` để xem plugin có trong danh sách đang bật chưa.

### Tên công cụ MCP khác với tài liệu

README giải thích hai đường cài dùng tên công cụ khác nhau. Plugin `ruflo-core` đăng ký MCP server riêng, công cụ có dạng `mcp__plugin_ruflo-core_ruflo__...`, còn đường CLI dùng tên gọn như `memory_store`. Nếu bạn làm theo hướng dẫn của đường này mà dùng đường kia, tên sẽ không khớp. Hãy chọn một đường và bám theo.

### Plugin bên ngoài bị nạp hai lần

Với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb` hay `agentic-flow`, README dặn chỉ cài từ **một** kho. Nếu bật từ cả hai kho thì mod và lệnh bị nạp hai lần. Gặp tình trạng này, tắt một bản đi.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có nhiều đường vào (Claude Code, Codex, MCP, terminal). Có bảng điều khiển để nhìn rõ agent đang làm gì và tốn bao nhiêu. Cơ chế cấp quyền cho Claude khá thận trọng: mặc định chỉ đọc và hỏi lại, hành động tốn tiền hay phá huỷ luôn cần xác nhận. Repo vẫn được cập nhật trong vài tháng gần đây, giấy phép MIT.

**Giới hạn.** Bộ công cụ rất lớn (README nhắc 406 công cụ MCP và 61 lệnh CLI), nên dễ choáng nếu muốn tìm hiểu hết. Đường `init` thêm khá nhiều file vào dự án. Phần "tự học" chỉ là mô hình khái niệm và vẫn cần embeddings cùng module cấu hình. README cũng thừa nhận các đoạn demo dùng dữ liệu mẫu, không chứng minh swarm đã làm xong việc thật. Các mod chạy không sandbox. Mình chưa thấy tư liệu nói về yêu cầu phần cứng hay chi phí gọi mô hình, nên bạn cần tự theo dõi chi phí qua công cụ bạn đang dùng.

**Nên chọn khi** bạn đã quen Claude Code hay Codex, làm việc với dự án mã nguồn có độ phức tạp vừa trở lên, và muốn nhiều agent phối hợp có kiểm soát. **Nên chọn cách khác khi** bạn chỉ cần trò chuyện hoặc sửa vài dòng mã: dùng thẳng Claude Code là đủ. Lời khuyên của mình: thử trong một thư mục dự án thử nghiệm, giao một việc nhỏ, rồi mới 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 bạn dùng mã nguồn được tự do. Tuy nhiên tư liệu chưa nói rõ về chi phí gọi mô hình AI phía sau. Phần đó phụ thuộc vào Claude Code, Codex hoặc nhà cung cấp mô hình bạn dùng, và README có plugin theo dõi chi phí để bạn kiểm soát.

### Cài Ruflo bằng lệnh nào, cần Node bản nào?

Chạy `npx ruflo@latest init` trong thư mục dự án. Gói yêu cầu Node từ bản 20.0.0 trở lên theo `package.json`. Sau đó mở lại Claude Code trong cùng thư mục.

### 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, bằng cách cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Cách điền cụ thể trong từng client thì bạn xem tài liệu của client đó.

### Cài plugin và chạy init khác nhau thế nào?

Plugin là bản nhẹ: không thêm file vào dự án, chủ yếu có lệnh gạch chéo và định nghĩa agent, cần Claude Code 2.1.287 trở lên. `npx ruflo@latest init` cho bộ đầy đủ gồm agent, lệnh, kỹ năng, MCP server, hook và daemon, đổi lại có thêm file như `.claude/` và `CLAUDE.md` trong dự án.

### Cho Claude điều khiển bảng điều khiển Ruflo có nguy hiểm không?

Bạn đặt được mức quyền: read, write, manage hoặc full, kèm chế độ duyệt ask hoặc auto. Mặc định hiện là read + ask. Hành động mạng, tốn tiền và phá huỷ vẫn cần xác nhận ngay cả khi để auto, và nút Take back control dừng việc điều khiển ngay.

### Ruflo có cần GPU hay máy cấu hình mạnh không?

Tư liệu phần đầu chưa nêu yêu cầu phần cứng. Một số plugin như `ruflo-ruvector` được mô tả là hỗ trợ tìm kiếm bằng GPU, nhưng README không nói đó là điều kiện bắt buộc. Muốn chắc, bạn xem tài liệu của plugin cụ thể.

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

README phần đầu chưa nêu danh sách hệ điều hành hỗ trợ. Điều kiện được ghi rõ là Node 20 trở lên và các lệnh `npx`. Bạn nên thử trên một thư mục dự án thử nghiệm trước, và xem mục Issues của repo nếu gặp lỗi riêng trên Windows.
