# 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 meta-harness: lớp công cụ bọc quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ qua nhiều phiên và cách điều phối nhiều agent cùng làm một việc. Cài bằng một lệnh npx trong thư mục dự án, cần Node 20 trở lên. Người mới cài được trong vài phút, nhưng nên bắt đầu từ lệnh init và một tác vụ nhỏ.

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

ruflo là một «agent meta-harness» cho Claude Code và Codex. Hiểu đơn giản: mô hình AI chỉ biết viết, còn ruflo là bộ khung bọc quanh nó, cấp thêm công cụ, bộ nhớ, vòng lặp và các giới hạn kiểm soát để AI làm được việc thật. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) tạo ra, viết chủ yếu bằng TypeScript, giấy phép MIT.

Vấn đề nó giải quyết rất quen thuộc. Khi bạn giao một việc lớn cho Claude Code, mỗi phiên làm việc gần như bắt đầu lại từ đầu, một agent làm tuần tự, và không có ai kiểm tra chéo. ruflo thêm hơn 100 agent chuyên biệt, cách chia việc cho cả «đội» agent (swarm), bộ nhớ nhớ qua các phiên và các lớp bảo vệ. Repo hiện có khoảng 81.582 sao và 9.607 fork, và vẫn được cập nhật trong vài tháng gần đây.

Bạn nên đọc bài này nếu bạn đã dùng Claude Code (hoặc Codex) và muốn nó xử lý việc dài hơi hơn: rà soát cả repo, viết test hàng loạt, theo dõi chi phí. Điểm đáng giá nhất là bạn không phải học hết hàng trăm công cụ. README nói rõ: sau khi chạy `init`, bạn cứ dùng Claude Code như bình thường, hooks sẽ 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, bộ nhớ, hooks và MCP server cho Claude Code và Codex, để AI làm việc theo nhóm thay vì từng phiên riêng lẻ.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README mô tả rất nhiều thứ. Mình gom lại những ý có lợi thực tế nhất.

- **Swarm (đội agent).** Thay vì một agent làm hết, nhiều agent chia nhau việc rồi gộp kết quả. Ví dụ: một agent tìm module rủi ro nhất, agent khác viết test. Bạn gọi bằng chính ngôn ngữ thường ngày trong Claude Code.
- **Bộ nhớ qua nhiều phiên.** Agent lưu lại kinh nghiệm và truy xuất lại bằng tìm kiếm vector. Lợi ích: lần sau bạn không phải giải thích lại cùng một bối cảnh dự án.
- **Hooks tự động.** Sau `init`, hooks tự định tuyến tác vụ và học từ các lần làm thành công. Bạn không cần gõ lệnh riêng cho từng việc.
- **Màn hình điều khiển (console).** Một «buồng lái» đặt cạnh Claude Code để theo dõi workflow, agent, mô hình, token và chi phí. Bạn có thể mở log từng agent, tìm kiếm, xem lại và so sánh các lần chạy.
- **Cho Claude điều khiển console, nhưng bạn đặt giới hạn.** Trong Settings → Claude control, bạn chọn mức `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 liên quan mạng, chi tiền hoặc phá huỷ luôn cần bạn xác nhận, kể cả ở chế độ `auto`.
- **Hệ thống plugin.** README liệt kê 48 plugin (cộng 3 plugin bên ngoài), 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-aidefence` chặn prompt injection và phát hiện thông tin cá nhân.
- **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. Phần này dành cho nhóm lớn, người mới chưa cần đụng tới.
- **Dùng được ngoài Claude Code.** Codex và các MCP client khác trỏ được vào ruflo. Có cả giao diện terminal chạy riêng.

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

Tư liệu nêu những điều sau, mình không thêm gì ngoài đó:

- **Node.js 20.0.0 trở lên.** `package.json` của repo yêu cầu như vậy. Lệnh `npx` đi kèm Node, nên bạn không cần cài thêm.
- **Claude Code** (hoặc Codex / một MCP client khác). Nếu muốn cài theo kiểu plugin trong Claude Code thì cần bản **2.1.287 trở lên**. Lệnh cài plugin từ terminal cần bản **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy `init`. Lệnh sẽ thêm file vào chính thư mục đó.

README phần đã cung cấp không nói gì về yêu cầu GPU hay dung lượng ổ đĩa. Mình cũng không thấy phần đã đọc nhắc cụ thể hệ điều hành nào, nên bạn xem thêm trong README đầy đủ của repo nếu cần chắc chắn. Về API key, phần README mình có không yêu cầu key riêng cho bước cài; bạn vẫn dùng tài khoản Claude Code hoặc Codex của mình như bình thường.

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

README có ba đường cài. Đường chính là một lệnh `npx`. Mình tóm tắt trước, rồi đi từng bước.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án bạn muốn thêm ruflo
- Chạy init | Một lệnh npx để thêm agent, hooks, bộ nhớ và MCP server
- Mở lại Claude Code | Khởi động Claude Code trong cùng thư mục để nó nhận cấu hình
- Giao một tác vụ thật | Gõ một câu yêu cầu dùng swarm của ruflo
- (Tuỳ chọn) Cài kiểu plugin hoặc MCP | Dành cho người không muốn thêm file vào dự án
```

### 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 thư mục dự án trước khi chạy. Trên Windows, bạn có thể mở PowerShell rồi `cd` vào thư mục. Nếu dự án nằm trên GitHub và bạn chưa tải về:

```bash
git clone https://github.com/<tài-khoản>/<dự-án-của-bạn>.git
cd <dự-án-của-bạn>
```

Hai chỗ `<...>` là tên dự án của bạn, không phải của ruflo. Nếu bạn đã có thư mục dự án rồi thì chỉ cần `cd` vào đó.

### 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 lệnh `init`. Theo README, `init` thêm agent, hooks, bộ nhớ và MCP server vào dự án. Bảng so sánh trong README cho biết cách này tạo các thư mục như `.claude/`, `.claude-flow/`, file `CLAUDE.md` và một số file hỗ trợ, nên nếu dự án đã có `CLAUDE.md` riêng, bạn nên sao lưu hoặc dùng Git để xem thay đổi.

Nếu muốn cấu hình qua các câu hỏi từng bước, README có thêm lệnh:

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

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

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

### Giao một tác vụ thật

Ví dụ README đưa ra để thử:

```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ó rồi tóm tắt thay đổi. Bạn có thể gõ nguyên văn tiếng Anh như trên, hoặc diễn đạt tương tự theo ý mình.

### Cách cài thay thế: chỉ dùng plugin Claude Code

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

Lần lượt: thêm kho plugin của ruflo, cài lõi, cài console, cài mods, nạp lại plugin, rồi mở console bằng `/ruflo`. Từ terminal, với Claude Code 2.1.292 trở lên, README có một lệnh một dòng:

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

```note
Mods 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 bạn đọc mã của mod trước khi cài. Hãy làm vậy, nhất là trên máy có dữ liệu quan trọng.
```

Bảng trong README cũng cho biết cách plugin nhẹ hơn: không có hooks, và chỉ `ruflo-core` mới đăng ký MCP server. Muốn đủ bộ (98 agent, hơn 60 lệnh, 30 skill, MCP server, hooks, daemon) thì dùng đường `npx ruflo@latest init`.

### Cách cài thay thế: Codex hoặc MCP client khác

Không cần thiết lập dự án. Bạn cấu hình **command** là `npx` và **arguments** như sau:

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

Nói cách khác, client sẽ chạy `npx -y ruflo@latest mcp start`. Chỗ điền cụ thể tuỳ từng ứng dụng; README đã cung cấp không hướng dẫn chi tiết cho từng client, nên bạn xem tài liệu của client bạn dùng.

### Cách thay thế: chạy giao diện terminal riêng

Console chạy được độc lập với Claude Code:

```bash
npx ruflo tui
```

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

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

Theo README, có vài dấu hiệu để biết cài thành công:

- **Sau `init`:** dự án xuất hiện các file/thư mục như `.claude/`, `.claude-flow/` và `CLAUDE.md`. Mở lại Claude Code trong thư mục đó.
- **Gõ `/ruflo` trong Claude Code:** console mở ra. README hướng dẫn quy trình là `npx ruflo init`, khởi động lại Claude Code, rồi `/ruflo`.
- **Cài kiểu plugin:** gõ `/plugin` và kiểm tra các mod xuất hiện trong dòng «active mods».
- **Chạy giao diện riêng:** `npx ruflo tui` hiện giao diện terminal.

README phần mình có không nêu một dòng kết quả cụ thể kiểu «in ra Hello». Vì vậy cách chắc chắn nhất là thử tác vụ nhỏ ở phần sau và xem Claude Code có gọi agent của ruflo hay không.

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

Dưới đây là các tình huống bám đúng khả năng README mô tả. Kết quả thật còn tuỳ dự án của bạn.

### Lập trình viên: rà soát một repo cũ và bổ sung test

Bạn nhận lại một dự án không ai nhớ rõ. Sau khi chạy `init` và mở lại Claude Code, bạn dùng đú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.
```

Kết quả mong đợi: các agent tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn đọc phần tóm tắt, rồi xem diff bằng Git trước khi giữ lại thay đổi.

### Người mới: thử điều khiển console mà vẫn giữ quyền kiểm soát

Bạn muốn xem ruflo làm gì mà không để nó tự ý hành động. README có một bài thử an toàn:

1. Cài console, mở `/ruflo`, chọn Settings → Claude control → **write + ask**.
2. Gõ yêu cầu: «Create a mission to add a dark mode toggle. Show me the mission and its status.»
3. Console hiện một hành động tạo mission đang chờ; bạn xác nhận.
4. Kiểm tra mục Missions có mục tiêu đó và Overview ghi lại hành động.

> Cứ để AI đề xuất, còn nút xác nhận phải nằm trong tay bạn.
>
> — Ông T

Lưu ý README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Nếu cần dừng, bấm **Take back control** và các lệnh Claude gọi sau đó sẽ bị từ chối cho đến khi bạn trả quyền lại.

### Trưởng nhóm: theo dõi chi phí token khi nhiều agent chạy song song

Chạy nhiều agent đồng nghĩa với tốn token nhanh hơn. README liệt kê plugin `ruflo-cost-tracker` («theo dõi token, đặt ngân sách, cảnh báo chi phí») và console hiển thị token cùng chi phí. Bạn cài plugin này theo cùng cách với các plugin khác:

```text
/plugin install ruflo-cost-tracker@ruflo
```

Lệnh này theo đúng mẫu `/plugin install <tên>@ruflo` mà README dùng cho các plugin khác. Kết quả: bạn có chỗ nhìn mức dùng và đặt ngưỡng cảnh báo, thay vì đến cuối tháng mới biết hoá đơn.

### Người làm việc với nhiều công cụ AI: dùng chung ruflo qua MCP

Bạn dùng Codex hoặc một ứng dụng hỗ trợ MCP. Bạn trỏ ứng dụng đó tới `npx -y ruflo@latest mcp start` như phần cài đặt đã nêu. Kết quả: công cụ của ruflo (bộ nhớ, điều phối) hiện trong ứng dụng đó mà không cần thêm file vào dự án.

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

Dưới đây là những lỗi rất dễ gặp với loại công cụ này. Mình nói rõ phần nào là suy đoán từ cách hoạt động, không phải README viết.

**1. Phiên bản Node quá cũ.** `package.json` yêu cầu Node 20 trở lên. Nếu `npx` báo lỗi khi chạy, gõ `node --version` để kiểm tra. Nếu thấp hơn 20, hãy cập nhật Node rồi chạy lại.

**2. Chạy `init` sai thư mục.** Lệnh này ghi file vào thư mục hiện tại. Nếu bạn chạy ở thư mục chứa nhiều dự án, các file sẽ nằm sai chỗ. Hãy `cd` vào đúng dự án trước, và dùng Git để xem các thay đổi mới được thêm.

**3. Claude Code không thấy agent của ruflo.** README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn rồi mở lại trong cùng thư mục. Với cách cài plugin, chạy `/reload-plugins` rồi `/plugin` để xem plugin có hiện chưa.

**4. Lệnh plugin báo không hợp lệ.** Cách cài plugin cần Claude Code 2.1.287 trở lên (lệnh `claude plugin install` từ terminal cần 2.1.292). Nếu bản của bạn cũ hơn, hãy cập nhật Claude Code hoặc dùng đường `npx ruflo@latest init`.

**5. Cài cùng một plugin từ hai nơi.** README cảnh báo với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`: chỉ nên cài từ một marketplace. Cài từ cả hai thì mod và lệnh bị nạp hai lần.

```note
Đừng nâng quyền Claude control lên `full` hoặc `auto` ngay từ đầu. Mặc định read + ask là mức an toàn nhất để làm quen. Hãy nâng dần khi bạn đã hiểu nó làm gì.
```

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Giấy phép MIT. Repo có cộng đồng lớn và vẫn được cập nhật. Có đường cài «nhẹ» chỉ bằng plugin, không thêm file vào dự án. Cơ chế giới hạn quyền cho Claude trong console được thiết kế khá cẩn thận: hành động nhạy cảm luôn cần bạn xác nhận.

**Giới hạn.** Hệ thống rất rộng: README nhắc tới 406 công cụ MCP, 61 lệnh CLI và 48 plugin. Với người mới, dễ bị ngợp. `init` thêm khá nhiều file vào dự án. Mods không chạy trong sandbox. Chi phí token tăng khi nhiều agent cùng chạy. README cũng tự nói rõ một số thứ chỉ là minh hoạ: video demo dùng dữ liệu mẫu và không chứng minh swarm đã hoàn thành công việc thật hay bộ nhớ đã truy xuất đúng. Phần «học liên tục» được mô tả là sơ đồ khái niệm. Đừng kỳ vọng phép màu.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code giúp sửa vài file nhỏ, bản thân Claude Code là đủ. Nếu bạn chỉ muốn thử một vài lệnh, hãy bắt đầu bằng đường plugin nhẹ. Chỉ chọn `init` đầy đủ khi bạn thật sự cần điều phối nhiều agent, bộ nhớ dài hạn và theo dõi chi phí cho dự án lớn.

Lời khuyên của mình: thử trên một dự án nhỏ hoặc một nhánh Git riêng, bắt đầu bằng một tác vụ như câu mẫu ở trên, rồi mới mở rộng.

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

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

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

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

Claude Code là công cụ AI viết code. ruflo là «harness» bọc quanh nó, thêm hơn 100 agent chuyên biệt, đội agent (swarm), bộ nhớ qua nhiều phiên, hooks và các lớp bảo vệ. Nó bổ sung chứ không thay thế Claude Code.

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

Cần Node.js 20 trở lên và một thư mục dự án để chạy lệnh npx ruflo@latest init. Nếu cài bằng plugin trong Claude Code thì cần bản 2.1.287 trở lên. Tư liệu chưa nói về yêu cầu GPU hay cấu hình phần cứng.

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

Phần README mình có không ghi rõ danh sách hệ điều hành được hỗ trợ. Công cụ chạy qua Node và npx nên bạn có thể thử, nhưng hãy xem README đầy đủ hoặc mục Issues của repo để chắc chắn.

### Có dùng với Codex hoặc ChatGPT được không?

Có. README nói Codex và các MCP client khác dùng được bằng cách trỏ tới lệnh npx -y ruflo@latest mcp start. README cũng nhắc tới phần ruOS Desktop có thể kết nối với ChatGPT hoặc Claude qua MCP.

### Claude có tự ý làm việc nguy hiểm trong console không?

Theo README, mặc định là read + ask. Bạn chọn mức quyền read, write, manage hoặc full, cùng chế độ ask hoặc auto. Hành động liên quan mạng, chi tiền hoặc phá huỷ vẫn cần xác nhận kể cả khi để auto, và nút Take back control dừng ngay quyền điều khiển.

### Cài plugin có thêm file vào dự án của mình không?

Nếu cài theo đường plugin Claude Code thì README nói là không thêm file nào vào dự án. Còn lệnh npx ruflo@latest init sẽ tạo các thư mục như .claude/, .claude-flow/ và file CLAUDE.md.
