# 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à bộ khung bao quanh Claude Code và Codex, giúp nhiều AI agent phối hợp thành một nhóm, có bộ nhớ qua các phiên làm việc và có kiểm soát quyền hạn. Bạn dùng nó để giao những việc nhiều bước như rà soát repo, viết test, tóm tắt thay đổi. Cài khá dễ: chỉ cần Node 20 trở lên và chạy 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-09-29 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-ai-agent-claude-code-codex-huong-dan-2

Ruflo là một "harness" (bộ khung điều phối) đặt quanh Claude Code và Codex. Nói đơn giản: mô hình AI là người viết, còn Ruflo là cái bàn làm việc đầy đủ đồ nghề quanh người đó. Nó thêm nhiều agent chuyên biệt, cách chia việc cho nhóm agent, bộ nhớ giữa các phiên và các lớp kiểm soát để AI làm việc có tổ chức hơn.

Nếu bạn đã dùng Claude Code và thấy mỗi lần mở lại là AI "quên sạch", hoặc muốn giao một việc lớn cho nhiều agent chia nhau làm, Ruflo đáng để thử. Người hợp nhất là lập trình viên, người làm sản phẩm, hoặc dân văn phòng đã quen chạy vài lệnh trong terminal. Repo hiện có khoảng 81.582 sao và 9.607 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.

Điểm đáng giá nhất là bạn không phải học 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, hệ thống hook sẽ tự định tuyến tác vụ và phối hợp agent chạy nền. Bạn chỉ cần mô tả việc cần làm.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung điều phối (harness) cho Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server vào dự án chỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những phần bạn sẽ thấy hữu ích nhất khi dùng thật.

### Nhóm agent chia việc cho nhau

Thay vì một AI làm tuần tự, Ruflo cho agent tự tổ chức thành "swarm" (đàn/nhóm). README nói có hơn 100 agent chuyên biệt. Với bạn, lợi ích là một yêu cầu lớn như "rà soát cả repo" được chia nhỏ: ai tìm chỗ rủi ro, ai viết test, ai tóm tắt.

### Bộ nhớ qua các phiên làm việc

Ruflo có bộ nhớ để agent nhớ lại kinh nghiệm từ các việc trước, và có plugin lưu/khôi phục bộ nhớ giữa các phiên. Bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code.

Tài liệu có ghi chú: vòng tự học là mô hình khái niệm. Phần 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 cấu hình.

### 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í. Bạn mở nhật ký chạy của từng agent, tìm kiếm, xem lại lỗi, so sánh các lần chạy. Gõ `/ruflo` trong Claude Code để mở.

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

Trong Settings có mục Claude control với các mức `read`, `write`, `manage`, `full`, kèm chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Theo README, hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận ngay cả khi ở chế độ `auto`. Có nút "Take back control" để thu lại quyền bất cứ lúc nào.

### Hơn 40 plugin cài theo nhu cầu

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 tập, kiểm thử, bảo mật, kiến trúc, DevOps. Ví dụ: `ruflo-testgen` tìm chỗ thiếu test và tạo test, `ruflo-cost-tracker` theo dõi token và đặt ngân sách, `ruflo-security-audit` quét lỗ hổng, `ruflo-aidefence` chặn prompt injection và phát hiện dữ liệu cá nhân.

### Chạy với Codex, client MCP khác, và cả Grok

Ngoài Claude Code, README nói Codex và các client MCP khác dùng được qua lệnh `npx -y ruflo@latest mcp start`. Có thêm tuỳ chọn `npx ruflo init --grok` cho Grok Build.

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

Tư liệu chỉ nêu một vài yêu cầu rõ ràng:

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json` của gói npm `claude-flow`.
- **Claude Code**, nếu bạn đi đường plugin: cần bản **2.1.287 trở lên**. Lệnh cài từ terminal (`claude plugin install ...`) cần bản **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy lệnh `init` (lệnh này thêm file vào dự án).
- Với Codex hoặc client MCP khác: client của bạn phải cấu hình được một MCP server theo kiểu "command + arguments".

Về hệ điều hành, GPU hay API key: README đoạn mình có không nói rõ yêu cầu phần cứng hay key riêng. Một số plugin (ví dụ chạy mô hình khác, cloud) có thể cần tài khoản hoặc dịch vụ đi kèm, bạn đọc mô tả từng plugin trước khi dùng.

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

Ruflo có hai đường cài khác nhau về "độ sâu". Mình khuyên người mới đi đường 1 (lệnh `init`) vì README gọi đây là đường cho "production use — everything works as documented".

```steps
- Kiểm tra Node | Chắc chắn máy có Node 20 trở lên
- Mở terminal trong dự án | Vào đúng thư mục dự án bạn muốn dùng
- Chạy init | Chạy một lệnh npx để thêm agent, hook, memory, MCP server
- Khởi động lại Claude Code | Mở Claude Code ở cùng thư mục để nó nhận cấu hình mới
- Giao một việc thật | Gõ yêu cầu dùng swarm của Ruflo
```

### Kiểm tra Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và gõ lệnh sau. Kết quả phải là phiên bản từ v20 trở lên.

```bash
node --version
```

Nếu thấy số nhỏ hơn 20 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.

### 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 một dự án có sẵn trên GitHub:

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

Thay phần trong dấu `< >` bằng tên thật. Nếu dự án đã nằm trên máy, bạn 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 và chạy Ruflo mà không cần cài toàn cục. Lệnh này thêm agent, hook, memory và MCP server vào dự án. README cho biết đường này tạo các thư mục như `.claude/`, `.claude-flow/` cùng file `CLAUDE.md` và một số file hỗ trợ, nên bạn sẽ thấy dự án có thêm file mới. Nếu dùng git, hãy xem `git status` sau đó để biết chính xác đã thêm gì.

Muốn thiết lập theo từng câu hỏi, README có lệnh:

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

### Khởi động lại Claude Code

Mở Claude Code ở cùng thư mục. README nói Claude Code sẽ nhận agent, hook, memory và MCP server ở lần khởi động kế tiếp. Nếu Claude Code đang mở sẵn lúc bạn chạy `init`, hãy đóng rồi mở lại.

### Đường thay thế: chỉ cài plugin trong Claude Code

Đường này không thêm file nào vào dự án và cần Claude Code 2.1.287 trở lên. Chạy từng dòng bên 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
```

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

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

Lưu ý README nói đường plugin chỉ cho một phần tính năng (lệnh slash, một số skill, định nghĩa agent), không có hook. Bộ đầy đủ là đường `init`.

```note
Mods chạy với quyền của tài khoản bạn và không bị sandbox. README khuyên bạn đọc mã nguồn trước khi cài. Với các plugin ngoài (như agentdb, agentic-flow), chỉ nên cài từ một marketplace duy nhất để tránh bị nạp hai lần.
```

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

Trong phần cấu hình MCP của client, đặt **command** là `npx` và **arguments** là:

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

Mỗi client điền ô này một kiểu, README không hướng dẫn giao diện cụ thể của từng client, nên bạn xem tài liệu của client đó để biết chỗ nhập.

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

Có vài cách để biết cài thành công, tuỳ đường bạn chọn:

- **Đường init:** sau khi chạy xong, thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md`. Mở lại Claude Code rồi gõ `/ruflo`. README cho biết đây là cách mở bảng điều khiển.
- **Đường plugin:** sau `/reload-plugins`, mở `/plugin` và xem Ruflo có xuất hiện trong dòng "active mods" không. Gõ `/ruflo` để mở console.
- **Chạy thử console ngoài Claude Code:** gõ lệnh dưới đây trong terminal. Nếu thấy giao diện terminal hiện lên là Ruflo chạy được.

```bash
npx ruflo tui
```

Thêm cờ `--plain` nếu bạn muốn in ra một khung hình duy nhất, phù hợp cho script:

```bash
npx ruflo tui --plain
```

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

Các tình huống dưới đây bám theo những gì README mô tả. Kết quả cụ thể phụ thuộc dự án và mô hình bạn dùng.

### Dev nhận dự án cũ: rà soát và viết test

Bạn mới nhận một repo không có người bàn giao. Sau khi `init` và mở lại Claude Code, bạn gõ đú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 chia nhau tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn vẫn nên đọc lại test trước khi gộp vào nhánh chính.

> Bạn vẫn viết code như cũ, còn việc phối hợp các agent thì để bộ khung lo.
>
> — Ông T

### Quản lý dự án: theo dõi chi phí và tiến độ ở một chỗ

Bạn không code nhiều nhưng muốn biết AI đang làm gì và tốn bao nhiêu. Mở `/ruflo` để xem workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Muốn đặt ngân sách và cảnh báo, README liệt kê plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí), cài bằng cùng kiểu lệnh `/plugin install`.

### Làm thử an toàn: để Claude tạo một "mission"

README có một bài thử từng bước rất hợp cho người mới, vì bạn giữ quyền duyệt:

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. Claude mở mục Missions và đặt mục tiêu. Bạn xác nhận thao tác tạo.
4. Kiểm tra mục Missions có mục tiêu và Overview có ghi lại hành động.

Cẩn thận hiểu đúng: tạo mission không có nghĩa là tính năng đã được làm xong. Nếu muốn dừng, bấm "Take back control".

### Dev có nhu cầu đặc thù: thêm plugin đúng việc

Tuỳ việc, bạn chọn plugin phù hợp: `ruflo-testgen` để tìm chỗ thiếu test, `ruflo-jujutsu` để phân tích git diff và chấm rủi ro, `ruflo-docs` để tạo và duy trì tài liệu, `ruflo-security-audit` để quét lỗ hổng. Cài từng cái bằng `/plugin install <tên>@ruflo`, ví dụ:

```text
/plugin install ruflo-testgen@ruflo
```

Bạn bắt đầu bằng một plugin, thấy hợp rồi mới thêm, đừng cài hết một lượt.

## 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 hay gặp nhất là Node quá cũ. Gói yêu cầu Node 20 trở lên. Chạy `node --version`, nếu thấp hơn thì nâng cấp Node rồi chạy lại.

### Claude Code không thấy agent hoặc lệnh /ruflo

Sau `init`, README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy đóng hẳn Claude Code, mở lại ở đúng thư mục dự án. Với đường plugin, chạy `/reload-plugins` rồi kiểm tra bằng `/plugin`.

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

Đường plugin cần Claude Code 2.1.287 trở lên, còn lệnh `claude plugin install` cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước khi thử lại.

### Dự án bỗng có thêm nhiều file lạ

Đây là hành vi bình thường của đường `init`: nó tạo `.claude/`, `.claude-flow/`, `CLAUDE.md` và các file hỗ trợ. Nếu bạn chưa muốn thay đổi dự án thật, hãy thử trên một bản sao, hoặc dùng đường plugin (README ghi là không thêm file nào vào workspace). Dùng git để xem và hoàn tác thay đổi.

### Plugin hoặc lệnh bị nạp hai lần

Với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow, README cảnh báo: nếu bật từ cả hai marketplace thì mod và lệnh sẽ nạp hai lần. Chỉ cài từ một nguồn.

## 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, cộng đồng lớn và repo còn được cập nhật. Nó cho bạn nhiều thứ trong một gói: nhóm agent, bộ nhớ, bảng điều khiển, kiểm soát quyền và hơn 40 plugin. Cơ chế "Claude control" với mức quyền và nút lấy lại quyền cho thấy tác giả có để ý đến an toàn.

**Giới hạn.** Hệ sinh thái rất rộng (README nhắc tới 406 công cụ MCP và 61 lệnh CLI), nên người mới dễ choáng. Đừng cố học hết. Ruflo cũng chỉ là lớp điều phối: chất lượng kết quả vẫn phụ thuộc mô hình bên dưới. README còn nói rõ một số bản demo dùng dữ liệu mẫu và không chứng minh swarm đã hoàn thành việc thật hay bộ nhớ đã nhớ lại đúng, nên bạn hãy tự thử trên việc nhỏ trước khi tin vào kết quả. Đường `init` thêm file vào dự án, còn mods chạy không sandbox.

**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 một file nhỏ, thì Claude Code thuần là đủ, thêm Ruflo chỉ làm rối. Nếu bạn không quen terminal hoặc chưa cài được Node, hãy học phần đó trước. Với dữ liệu nhạy cảm, hãy đọc kỹ từng plugin và quyền nó cần trước khi bật, vì README không đưa cam kết chung về bảo mật dữ liệu cho mọi trường hợp.

Lời khuyên của mình: thử trên một dự án nhỏ hoặc bản sao, giữ mức quyền read hoặc write kèm ask, giao một việc cụ thể như câu mẫu ở trên, 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 mã nguồn dùng tự do. Tuy vậy Ruflo chạy trên Claude Code, Codex hoặc các nhà cung cấp AI khác, và README đoạn mình có không nêu chi phí của các dịch vụ đó. Bạn nên xem gói và mức phí của chính công cụ AI bạn dùng, và có thể dùng bảng điều khiển hoặc plugin ruflo-cost-tracker để theo dõi token.

### Ruflo cần Node phiên bản nào?

File package.json của gói yêu cầu Node từ 20.0.0 trở lên. Bạn kiểm tra bằng lệnh node --version. Nếu thấp hơn, hãy nâng cấp Node trước khi chạy npx ruflo@latest init.

### Ruflo khác gì dùng Claude Code thuần?

Claude Code thuần là một AI làm việc trong dự án của bạn. Ruflo thêm lớp bao quanh: nhiều agent chuyên biệt, nhóm agent phối hợp, bộ nhớ qua các phiên, bảng điều khiển và các lớp kiểm soát. README mô tả nó là agent meta-harness cho Claude Code và Codex.

### Cài Ruflo có làm thay đổi dự án của tôi không?

Có, nếu bạn dùng npx ruflo init: README nói đường này tạo .claude/, .claude-flow/, CLAUDE.md và một số file hỗ trợ. Nếu không muốn thêm file, bạn dùng đường plugin trong Claude Code, README ghi là không thêm file nào vào workspace, nhưng chỉ có một phần tính năng.

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

Được. README nói Codex và các client MCP khác dùng được bằng cách cấu hình command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Cách điền cụ thể tuỳ từng client, README không hướng dẫn chi tiết.

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

README mô tả các mức quyền read, write, manage, full cùng chế độ duyệt ask hoặc auto, mặc định là read + ask. Hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả ở chế độ auto, và có nút Take back control để thu lại quyền. Bạn vẫn nên giữ mức quyền thấp khi mới thử.

### Chạy trên Windows và có cần GPU không?

README đoạn mình có không nêu yêu cầu hệ điều hành hay GPU cho đường cài chính. Yêu cầu rõ ràng duy nhất là Node 20 trở lên (và Claude Code đủ mới nếu dùng plugin). Một vài plugin riêng, như plugin tìm kiếm tăng tốc GPU, có thể có yêu cầu thêm, bạn xem mô tả từng plugin.
