# 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: lớp công cụ bọc quanh Claude Code và Codex, thêm các agent chuyên biệt, bộ nhớ qua nhiều phiên, hook tự động và máy chủ MCP. Bạn chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án rồi mở lại Claude Code. Cài không khó, nhưng cần Node 20 trở lên và đã có sẵn Claude Code hoặc một ứng dụng khách MCP.

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

ruflo là một “agent harness” — tức là bộ khung đặt quanh Claude Code và Codex để các AI agent làm việc có tổ chức hơn. Hiểu đơn giản: mô hình AI lo phần viết, còn ruflo lo phần công cụ, bộ nhớ, vòng lặp và các giới hạn an toàn để agent làm được việc thật. Repo này trước đây có tên Claude Flow và hiện có khoảng 81,6 nghìn sao cùng 9,6 nghìn fork trên GitHub.

Nếu bạn đang dùng Claude Code mà thấy mỗi phiên làm việc lại phải giải thích từ đầu, hoặc muốn nhiều agent chia việc cho nhau (người viết code, người viết test, người rà soát), ruflo được làm ra cho đúng nhu cầu đó. Nó hợp với lập trình viên và những bạn đã bắt đầu dùng Claude Code cho công việc thường ngày.

Điểm đáng giá nhất là cách cài rất gọn: một lệnh `init` trong thư mục dự án, sau đó bạn cứ dùng Claude Code như bình thường. README nói rõ bạn không cần học hết hàng trăm công cụ MCP hay hàng chục lệnh CLI; hệ thống hook sẽ tự định tuyến tác vụ và điều phối agent ở nền.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) thêm agent, bộ nhớ, hook và máy chủ MCP cho Claude Code và Codex, để nhiều agent phối hợp làm việc chỉ với một lệnh init.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là các tính năng chính theo README, kèm lợi ích thực tế.

### Nhiều agent làm việc như một nhóm

ruflo cung cấp rất nhiều agent chuyên biệt và cho chúng tự tổ chức thành “swarm” (bầy/nhóm). Thay vì một agent ôm hết mọi việc, bạn có thể yêu cầu cả nhóm cùng xử lý: tìm module rủi ro nhất, viết test, rồi tóm tắt thay đổi. Việc chia nhỏ này giúp tác vụ lớn đỡ bị rối.

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

README mô tả bộ nhớ tự học: agent nhớ lại kinh nghiệm từ các tác vụ đã thành công và dùng lại để định tuyến những việc sau. Các plugin như ruflo-agentdb (cơ sở dữ liệu vector cho bộ nhớ agent) và ruflo-rvf (lưu và khôi phục bộ nhớ giữa các phiên) phục vụ phần này. Lợi ích: bạn đỡ phải nhắc lại bối cảnh dự án mỗi lần.

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

Plugin ruflo-console là một “buồng lái” để theo dõi workflow, agent, mô hình, token và chi phí cạnh Claude Code. Bạn có thể mở nhật ký chạy của từng agent, tìm kiếm, phát hiện lỗi, phát lại và so sánh. Mở bằng lệnh `/ruflo` trong Claude Code.

### Để Claude điều khiển nhưng bạn đặt giới hạn

Trong phần Settings của console có mục “Claude control”. Bạn chọn mức quyền `read`, `write`, `manage` hoặc `full`, và chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các hành động vượt quyền sẽ bị từ chối, còn hành động liên quan mạng, chi tiêu hay phá huỷ vẫn phải xác nhận kể cả khi đang `auto`. Bạn có thể bấm “Take back control” để lấy lại quyền bất cứ lúc nào.

### Hệ sinh thái plugin

README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia nhóm: điều phối (swarm, workflows, autopilot), bộ nhớ và tri thức, học và trí tuệ, chất lượng mã (ruflo-testgen sinh test, ruflo-docs viết tài liệu, ruflo-jujutsu phân tích git diff), bảo mật (ruflo-security-audit, ruflo-aidefence), và vận hành (ruflo-cost-tracker theo dõi token, đặt ngân sách, cảnh báo chi phí). Bạn chỉ cần cài cái mình cần.

### Liên kết nhiều máy

Phần federation cho phép agent trên các máy khác nhau trao đổi với nhau một cách an toàn. Đây là tính năng nâng cao; người mới chưa cần đụng tới.

### Dùng được với Codex và ứng dụng MCP khác

Ngoài Claude Code, README nói Codex và các ứng dụng khách MCP khác cũng dùng được bằng cách trỏ tới lệnh `npx -y ruflo@latest mcp start`. Có thêm tuỳ chọn `--grok` cho Grok Build.

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

Theo tư liệu, bạn cần:

- Node.js phiên bản 20.0.0 trở lên (package.json ghi `>=20.0.0`). Lệnh `npx` đi kèm Node.
- Claude Code, nếu bạn đi theo đường chính. Riêng đường cài plugin thì cần Claude Code 2.1.287 trở lên; lệnh cài plugin từ terminal cần 2.1.292 trở lên.
- Hoặc một ứng dụng khách MCP như Codex nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy `init`.

Về hệ điều hành, yêu cầu GPU, tài khoản hay API key: phần README mình có không nói cụ thể, nên mình không khẳng định gì thêm. Bạn dùng Claude Code hay Codex thì cần tài khoản/khoá của chính các công cụ đó theo cách bạn vẫn dùng.

```note
Các mod của ruflo chạy với quyền tài khoản của bạn và không bị đặt trong hộp cát (sandbox). README khuyên đọc mã nguồn trước khi cài. Hãy giữ mức quyền “Claude control” ở read + ask cho tới khi bạn quen, vì tăng quyền là lựa chọn của bạn.
```

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

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án mà bạn muốn thêm ruflo
- Chạy init | Dùng npx để thêm agent, hook, bộ nhớ và máy chủ MCP vào dự án
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao một tác vụ thật | Dán câu lệnh mẫu để thử swarm
- (Tuỳ chọn) Cài console | Cài plugin ruflo-console rồi gõ /ruflo
```

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

Đây là chỗ người mới hay vấp nhất: `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 dùng `cd` để vào thư mục. Ví dụ dưới đây là đường dẫn minh hoạ, bạn thay bằng thư mục của mình:

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

### Chạy lệnh init

Đây là lệnh chính theo 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à máy chủ MCP vào dự án. Ở bảng so sánh, README nói đường CLI này tạo các thư mục/tệp như `.claude/`, `.claude-flow/`, `CLAUDE.md`, các tệp hỗ trợ và settings trong thư mục làm việc. Nếu bạn muốn thiết lập theo kiểu hỏi đáp từng bước, có lệnh:

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

### Mở lại Claude Code

README cho biết Claude Code sẽ nhận các thứ vừa thêm ở lần khởi động kế tiếp. Vì vậy hãy thoát Claude Code (nếu đang mở) và mở lại trong cùng thư mục.

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

Gõ câu lệnh 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 nhờ cả nhóm agent rà soát repo, tìm module rủi ro nhất, viết test cho nó và tóm tắt các thay đổi. Bạn có thể viết bằng tiếng Việt nếu muốn, nhưng mẫu gốc là tiếng Anh nên mình giữ nguyên.

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

Nếu bạn không muốn thêm tệp nào vào dự án, README có đườ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
```

Đường này cài công cụ lõi, bảng điều khiển và các mod, và không thêm tệp nào vào dự án. Từ terminal, với Claude Code 2.1.292 trở lên, README ghi lệnh:

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

Lưu ý: theo bảng so sánh của README, đường plugin chỉ cho lệnh gạch chéo và một vài skill, không có hook. Muốn đủ vòng lặp ruflo như tài liệu mô tả thì dùng đường `npx ruflo@latest init`.

### Cách khác: Codex hoặc ứng dụng MCP khác

Với Codex hay ứng dụng khách MCP khác, bạn cấu hình **command** là `npx` và **arguments** như sau:

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

Cách điền cụ thể vào từng ứng dụng thì README (phần mình có) chưa chỉ chi tiết; bạn xem trong tài liệu của ứng dụng đó, mục thêm máy chủ MCP.

### Cách khác: chạy console trong terminal thường

Bảng điều khiển có thể chạy độc lập, không cần 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

Có vài dấu hiệu theo README:

- Sau `init` và khởi động lại, thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Nếu cài console, gõ `/ruflo` trong Claude Code sẽ mở bảng điều khiển. Mở `/plugin` để thấy các mod xuất hiện trong dòng “active mods”.
- Chạy câu lệnh mẫu về swarm và xem Claude có điều phối agent, viết test và tóm tắt thay đổi hay không.

Bài thử an toàn nhất là tạo một “mission” trong console. Vào Settings, mục Claude control, chọn write + ask, rồi nhập yêu cầu:

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

Claude sẽ mở trang Missions và đặt mục tiêu; bạn xác nhận hành động tạo. Sau đó kiểm tra mục Missions có mục tiêu mới và trang Overview có ghi lại hành động. README nhắc: tạo mission không có nghĩa là tính năng đã được làm xong.

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

### Lập trình viên rà soát và viết test cho dự án cũ

Bạn vừa nhận một dự án chưa ai viết test. Sau khi chạy `init` và mở lại Claude Code, bạn dán câu lệnh mẫu của README để nhờ swarm tìm module rủi ro nhất, viết test và tóm tắt thay đổi. Kết quả bạn nhận là các tệp test mới cùng bản tóm tắt những gì đã sửa; bạn đọc lại từng thay đổi trước khi giữ. Nếu muốn chuyên hơn, plugin ruflo-testgen được mô tả là tìm test còn thiếu và sinh test tự động.

> Agent = Model + Harness: mô hình viết, còn harness cho nó công cụ, bộ nhớ và giới hạn để làm việc thật.
>
> — Ông T

### Theo dõi chi phí khi agent chạy lâu

Bạn dùng agent nhiều và lo hoá đơn token. Cài plugin ruflo-cost-tracker, mà README mô tả là theo dõi lượng token, đặt ngân sách và báo động chi phí. Kết hợp với console để xem token và chi phí ngay cạnh Claude Code. Kết quả: bạn nhìn thấy mỗi tác vụ tốn bao nhiêu thay vì đoán mò. Cách cài plugin cụ thể bạn làm theo mẫu `/plugin install <tên-plugin>@ruflo` như ở trên.

### Người mới thử an toàn, không đụng vào dự án

Bạn chưa muốn thêm tệp nào vào dự án thật. Dùng đường plugin: thêm marketplace, cài ruflo-core, ruflo-console, ruflo-mods rồi gõ `/ruflo`. Bạn xem bảng điều khiển, thử tạo mission ở mức write + ask và tập dùng nút Take back control. Kết quả: bạn hiểu cách ruflo vận hành mà không để lại tệp nào trong dự án. Khi thấy hợp, bạn mới chạy `npx ruflo@latest init`.

### Dùng với Codex hoặc công cụ MCP khác

Bạn làm việc chủ yếu bằng Codex. Bạn thêm một máy chủ MCP với command `npx` và arguments `-y`, `ruflo@latest`, `mcp`, `start`. Từ đó Codex gọi được các công cụ của ruflo. Mình chưa có tư liệu chi tiết về từng công cụ cụ thể sẽ hiện ra trong Codex, nên bạn thử và xem danh sách công cụ mà ứng dụng của bạn hiển thị.

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

### Báo lỗi phiên bản Node

Nếu máy bạn dùng Node cũ hơn 20, `npx` có thể lỗi hoặc ruflo không chạy. package.json yêu cầu Node từ 20.0.0. Kiểm tra bằng `node --version`, rồi nâng cấp Node nếu cần.

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

Cclaude Code chỉ nhận cấu hình ở lần khởi động kế tiếp. Hãy thoát hẳn và mở lại trong đúng thư mục bạn đã chạy `init`. Nếu mở nhầm thư mục khác, nó sẽ không thấy các tệp `.claude/` vừa tạo.

### Lệnh /plugin không nhận hoặc plugin không xuất hiện

Đường plugin cần Claude Code 2.1.287 trở lên. Hãy cập nhật Claude Code, sau đó chạy `/reload-plugins` và mở `/plugin` để kiểm tra danh sách mod đang bật.

### Plugin chạy hai lần

README cảnh báo với các plugin bên ngoài như agentic-qe-fleet, agentdb và agentic-flow: chỉ cài từ một marketplace, không cài từ cả hai. Nếu bật từ cả hai nơi, mod và lệnh của chúng sẽ bị nạp hai lần. Hãy gỡ một bản.

### Claude làm hành động ngoài ý muốn

Nếu bạn nâng quyền “Claude control” lên mức cao, Claude có thể làm nhiều việc hơn. Hãy đưa về read + ask, hoặc bấm “Take back control” để dừng. Xem nhật ký hành động trực tiếp để biết Claude đã làm gì. Hành động liên quan mạng, chi tiêu hay phá huỷ vẫn cần bạn xác nhận.

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

**Điểm mạnh.** Cài rất nhanh chỉ với một lệnh, giấy phép MIT, repo vẫn được cập nhật trong khoảng 3 tháng gần đây. Hệ sinh thái plugin rộng, có bảng điều khiển để nhìn thấy agent đang làm gì, và có cơ chế phân quyền rõ ràng để bạn giữ quyền kiểm soát. Dùng được với cả Claude Code lẫn Codex.

**Giới hạn.** Dự án khá lớn và có nhiều khái niệm (swarm, federation, hook, mod). Người mới dễ choáng nếu cố tìm hiểu hết ngay. `init` thêm khá nhiều tệp vào dự án, nên nên thử trên một dự án nháp trước. README cũng nói rõ các bản demo dùng dữ liệu mẫu hoặc phát lại khung hình, không phải bằng chứng cho việc swarm đã hoàn thành công việc thật. Phần học tự động cũng được README gọi là mô hình khái niệm, và vẫn cần các mô-đun embedding đã cấu hình. Mình chưa có thông tin về mức ổn định trên từng hệ điều hành.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code trả lời vài câu hỏi hoặc sửa file nhỏ, dùng thẳng Claude Code là đủ. Nếu bạn chưa quen dòng lệnh hay chưa có Claude Code/Codex, hãy làm quen các công cụ đó trước. Còn nếu bạn muốn chia việc cho nhiều agent, có bộ nhớ và có bảng theo dõi, ruflo là lựa chọn đáng thử, và bạn nên bắt đầu từ đường plugin hoặc một dự án nháp.

## 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 mã nguồn mở và dùng tự do. Tuy nhiên ruflo chạy trên Claude Code, Codex hoặc các nhà cung cấp mô hình khác, nên chi phí dùng các dịch vụ đó vẫn theo gói của bạn. Plugin ruflo-cost-tracker giúp theo dõi token và ngân sách.

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

Lệnh chính là `npx ruflo@latest init`, chạy trong thư mục dự án. package.json yêu cầu Node từ 20.0.0 trở lên. Sau đó bạn mở lại Claude Code trong cùng thư mục.

### Dùng ruflo có cần GPU không?

Tư liệu mình có không nêu yêu cầu GPU cho đường cài thông thường. Có một plugin tên ruflo-ruvector được mô tả là tìm kiếm tăng tốc bằng GPU, nhưng đó là plugin tuỳ chọn. Bạn nên xem README trong repo nếu định dùng nó.

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

Tư liệu mình có chưa nói rõ về hệ điều hành được hỗ trợ. Điều chắc chắn là cần Node 20 trở lên và `npx`. Bạn nên thử trên dự án nháp, và xem mục Issues của repo nếu gặp lỗi riêng của Windows.

### Ngoài Claude Code, ruflo dùng được với công cụ nào?

README nói Codex và các ứng dụng khách MCP khác dùng được: cấu hình command là `npx` với arguments `-y`, `ruflo@latest`, `mcp`, `start`. Có thêm tuỳ chọn `npx ruflo init --grok` cho Grok Build. Bạn cũng có thể chạy console độc lập bằng `npx ruflo tui`.

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

Đường plugin không thêm tệp nào vào dự án, chỉ cho lệnh gạch chéo, vài skill và định nghĩa agent. Đường `npx ruflo@latest init` mới cho đủ vòng lặp: nhiều agent, lệnh, skill, máy chủ MCP, hook và daemon. README khuyên đường init cho dùng thực tế.

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

README mô tả bốn mức quyền (read, write, manage, full) và hai chế độ duyệt (ask, auto), mặc định là read + ask. 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 auto. Bạn có thể bấm Take back control để dừng. Còn các mod chạy với quyền tài khoản của bạn và không bị sandbox, nên cần đọc mã trước khi cài.
