# Ruflo: điều phối nhiều agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

> Ruflo là một agent harness (lớp điều phối) bao quanh Claude Code và Codex, thêm agent, bầy agent (swarm), bộ nhớ dài hạn, hook và MCP server vào dự án của bạn. Bạn dùng nó để giao việc lớn cho nhiều agent phối hợp thay vì một agent đơn lẻ. 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-25 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-ai-claude-code-codex-huong-dan-2

Ruflo là một «agent harness»: lớp công cụ bao quanh Claude Code và Codex, giúp mô hình AI không chỉ trả lời mà còn làm việc có tổ chức. Nó bổ sung agent chuyên biệt, bầy agent phối hợp (swarm), bộ nhớ qua nhiều phiên, hook tự động và một MCP server. 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.

Tác giả diễn đạt ý tưởng đơn giản thế này: Agent = Model + Harness. Mô hình lo phần viết, còn harness cấp công cụ, bộ nhớ, vòng lặp và các giới hạn kiểm soát để agent làm việc được thật. Ruflo chính là phần harness đó.

Bạn nên xem Ruflo nếu đang dùng Claude Code hoặc Codex và muốn giao những việc dài hơi: rà soát cả repo, viết test, theo dõi tiến độ nhiều bước. Điểm đáng giá nhất là bạn không phải học hết công cụ. README nói rõ: sau khi `init`, cứ dùng Claude Code như bình thường, hệ thống hook sẽ tự định tuyến việc, học từ các lần thành công và điều phối agent ở nền.

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

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

Tài liệu của repo khá rộng. Dưới đây là những phần dễ thấy lợi ích nhất với người mới.

### Agent và swarm

Sau khi cài theo cách đầy đủ, dự án của bạn có sẵn khoảng 98 agent, hơn 60 lệnh và 30 skill (theo bảng so sánh trong README). Các agent có thể tự tổ chức thành swarm, tức một nhóm chia việc cho nhau. Lợi ích thực tế: bạn mô tả một mục tiêu lớn, Claude Code có thể chia nhỏ rồi giao cho nhiều agent thay vì tự làm tuần tự.

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

Ruflo có bộ nhớ vector để agent nhớ lại thứ đã làm ở các phiên trước. Các plugin như ruflo-agentdb, ruflo-rag-memory và ruflo-rvf phụ trách việc lưu, tìm kiếm và khôi phục bộ nhớ. Với người dùng, điều này nghĩa là đỡ phải giải thích lại bối cảnh dự án mỗi lần mở máy.

### Học từ kinh nghiệm

README mô tả một vòng học: kinh nghiệm từ các tác vụ thành công được đưa ngược lại vào việc định tuyến. README cũng ghi thận trọng rằng đây là sơ đồ khái niệm, và phần học cục bộ vẫn cần embedding cùng các module học được cấu hình. Bạn đừng kỳ vọng nó tự thông minh lên ngay.

### Bảng điều khiển (console) trong Claude Code

Plugin ruflo-console cho bạn một «buồng lái» cạnh Claude Code để theo dõi workflow, agent, model, token và chi phí. Bạn mở bằng lệnh `/ruflo`. Có thể xem log từng agent, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy.

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

Trong Settings → 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; hành động liên quan mạng, chi tiêu hoặc phá hủy vẫn phải xác nhận kể cả khi để `auto`. Có nút «Take back control» để thu quyền lại.

### Hệ sinh thái 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-security-audit quét lỗ hổng, ruflo-cost-tracker theo dõi token và đặt ngân sách. Bạn chỉ cần cài cái mình cần.

### Liên kết nhiều máy và nhiều công cụ

Ruflo hỗ trợ federation (agent ở các máy khác nhau phối hợp) và có thể dùng với Codex hoặc client MCP khác. README cũng có lệnh `npx ruflo init --grok` cho Grok Build. Phần này dành cho người dùng nâng cao, người mới chưa cần đụng tới.

## 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 yêu cầu `>=20.0.0`).
- Claude Code (hoặc Codex, hoặc một client MCP khác) để dùng cùng.
- Nếu chọn cách cài bằng plugin: Claude Code phiên bản 2.1.287 trở lên. Lệnh cài từ terminal thì cần 2.1.292 trở lên.
- Một thư mục dự án để chạy lệnh `init`.

Tư liệu không nêu yêu cầu về hệ điều hành hay GPU, và README phần đầu không nói rõ cần API key nào. Ruflo chạy bên cạnh Claude Code hoặc Codex nên bạn vẫn cần tài khoản hợp lệ của công cụ đó. Plugin ruflo-ruvector có nhắc tìm kiếm tăng tốc GPU, nhưng đó là tùy chọn riêng của plugin, không phải điều kiện để dùng Ruflo.

```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 sandbox. README khuyên đọc mã nguồn trước khi cài. Hãy để chế độ Claude control ở mức read + ask khi mới làm quen.
```

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

README có nhiều đường cài. Cách đơn giản và đầy đủ nhất là `npx ruflo@latest init`. Hai cách còn lại (plugin và MCP) mình trình bày sau để bạn chọn.

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

### Kiểm tra Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) và xem phiên bản Node. Lệnh `node --version` là lệnh phổ thông. Kết quả phải từ v20 trở lên.

```bash
node --version
```

Nếu thấp hơn 20, bạn cần nâng cấp Node trước. README không hướng dẫn việc này, hãy xem trang chính thức của Node.js.

### Mở terminal đúng thư mục

Đâ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. Nếu bạn chưa có thư mục nào, tạo một thư mục thử rồi `cd` vào đó.

```bash
cd đường-dẫn-tới-dự-án-của-bạn
```

Thay phần sau `cd` bằng đường dẫn thật trên máy bạn.

### Chạy init

Đây là lệnh chính theo README:

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

`npx` tải và chạy gói tạm thời, không cần cài toàn cục. Lệnh này thêm agent, hook, bộ nhớ và MCP server của Ruflo vào dự án. Theo bảng so sánh trong README, cách này tạo các mục như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings trong workspace. Vì vậy hãy chạy trong dự án có dùng git để dễ xem những gì đã thay đổi.

Nếu muốn thiết lập theo kiểu hỏi đáp, README ghi có lệnh:

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

### Mở lại Claude Code và giao việc thử

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thành phần ở lần khởi động kế tiếp. Nếu Claude Code đang mở sẵn, hãy thoát ra và mở lại. Sau đó thử một việc thật, 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.
```

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

Cách này không thêm file nào vào dự án và cần Claude Code 2.1.287 trở lên. Gõ các lệnh sau 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
```

Từ terminal, trên Claude Code 2.1.292 trở lên, README ghi lệnh:

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

Lưu ý README nói rõ cách plugin là bản «nhẹ»: chỉ có lệnh slash, vài skill và định nghĩa agent. Không có hook, và MCP server chỉ được đăng ký khi bạn cài ruflo-core. Muốn dùng đủ vòng lặp của Ruflo thì chọn `npx ruflo@latest init`.

### Cách khác: Codex hoặc client MCP khác

Với Codex hay client MCP, bạn cấu hình lệnh (command) là `npx` và đối số (arguments) như sau:

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

Tương đương dòng lệnh `npx -y ruflo@latest mcp start`. Cách này không cần thiết lập dự án.

### Cách khác: giao diện terminal

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

```bash
npx ruflo tui
```

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

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

Sau `npx ruflo@latest init`, hãy kiểm tra theo thứ tự này:

1. Trong thư mục dự án có xuất hiện các mục như `.claude/`, `.claude-flow/` và `CLAUDE.md` (theo README cho cách cài CLI).
2. Mở lại Claude Code trong thư mục đó, rồi gõ `/ruflo`. Nếu bảng điều khiển hiện ra, phần console đã hoạt động.
3. Nếu cài bằng plugin, gõ `/plugin` để xem các mod có nằm trong dòng «active mods» không.
4. Giao thử câu lệnh swarm mẫu ở trên và xem Claude Code có phản hồi bằng cách dùng agent của Ruflo hay không.

README không đưa ra một dòng kết quả cố định kiểu «cài thành công». Vì vậy cách kiểm tra đáng tin nhất là thấy file mới xuất hiện và `/ruflo` mở được.

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

### Lập trình viên rà soát một repo lạ

Bối cảnh: bạn vừa nhận một dự án cũ, chưa ai viết test. Chạy `npx ruflo@latest init` trong thư mục dự án, mở lại Claude Code rồi dán câu lệnh 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: agent chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Hãy đọc kỹ phần test được sinh ra trước khi gộp vào nhánh chính. Vì có hạ tầng nhiều agent, bạn nên xem lại chứ không nên tin ngay.

> Cứ dùng Claude Code như bình thường, phần điều phối để Ruflo lo ở nền.
>
> — Ông T

### Người mới theo dõi agent bằng bảng điều khiển

Bối cảnh: bạn muốn biết agent đang làm gì và tốn bao nhiêu token. Cài plugin ruflo-console theo cách plugin ở trên, rồi gõ `/ruflo`. Bạn xem được workflow, agent, model, token và chi phí; mở log từng agent để biết nó đã làm gì khi có lỗi. Kết quả: bạn nhìn thấy quá trình thay vì chờ một kết quả cuối không rõ nguồn gốc.

### Giao Claude tạo «mission» có kiểm soát

Bối cảnh: bạn muốn thử cho Claude điều khiển bảng điều khiển nhưng sợ nó làm quá tay. README có một ví dụ từng bước:

1. Mở `/ruflo`, vào Settings → Claude control, chọn write + ask.
2. Đưa yêu cầu cụ thể:

```text
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 đang chờ.
4. Kiểm tra mục Missions có mục tiêu đó và Overview có ghi lại hành động.
5. Bấm «Take back control» khi muốn dừng quyền của Claude.

README nhắc rõ: tạo mission không có nghĩa là tính năng đã được làm xong.

### Nhóm nhỏ kiểm soát chi phí và chất lượng bằng plugin

Bối cảnh: một nhóm nhỏ dùng Claude Code hằng ngày và lo chi phí token. Họ cài thêm plugin theo cú pháp `/plugin install <tên>@ruflo`, ví dụ ruflo-cost-tracker (theo dõi token, đặt ngân sách, cảnh báo chi phí) và ruflo-testgen (tìm test thiếu và sinh test). README chỉ mô tả ngắn gọn chức năng, nên hãy thử trên một dự án nhỏ trước khi đưa vào quy trình chính.

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

### Chạy lệnh nhưng Claude Code không thấy gì mới

Nguyên nhân hay gặp: Claude Code đang mở từ trước hoặc mở sai thư mục. README nói các thành phần được nhận ở lần khởi động kế tiếp. Hãy thoát Claude Code, mở lại đúng thư mục đã chạy `init`. Với plugin, thử `/reload-plugins`.

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

Nếu `npx` báo lỗi lạ, hãy chạy `node --version`. Tư liệu yêu cầu Node 20 trở lên. Nâng Node lên rồi chạy lại.

### Lệnh `/plugin install` không chạy hoặc không có

Cách plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 trở lên cho lệnh `claude plugin install` ở terminal). Cập nhật Claude Code trước. Nhớ gõ các lệnh `/plugin ...` bên trong Claude Code, không gõ vào terminal thường.

### Tên công cụ MCP không khớp khi dùng cách plugin

README giải thích: với plugin ruflo-core, công cụ có tên dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, khác tên ngắn như `memory_store` của cách cài CLI. Nếu bạn làm theo tài liệu viết cho cách CLI mà dùng cách plugin, tên sẽ lệch. Hãy chọn một cách cho nhất quán, hoặc dùng cách CLI nếu muốn đúng như tài liệu.

### Cài trùng plugin từ hai nguồn

Với các plugin ngoài như agentic-qe-fleet, agentdb, agentic-flow, README dặn chỉ cài từ một marketplace. Nếu bật từ cả hai, mod và lệnh có thể tải hai lần. Hãy gỡ một bê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, repo vẫn được cập nhật trong vài tháng gần đây. Nó cho bạn phần điều phối, bộ nhớ và bảng theo dõi mà Claude Code mặc định không có. Cơ chế phân quyền (read/write/manage/full, ask/auto) cũng cho bạn quyền kiểm soát rõ ràng.

Giới hạn: dự án rất lớn (README nhắc tới 406 công cụ MCP và 61 lệnh CLI), nên người mới dễ bị ngợp. Cách cài đầy đủ ghi khá nhiều file vào dự án. Phần tự học được README mô tả là «khái niệm», chưa phải thứ bạn nên mặc định tin. Các mod không bị sandbox, nên cần đọc mã trước khi cài.

Nên chọn cách khác khi: bạn chỉ cần Claude Code cho việc nhỏ lẻ, một agent là đủ; hoặc bạn không muốn thêm file cấu hình vào dự án (khi đó thử cách plugin, hoặc không dùng). Nếu bạn là người mới, hãy bắt đầu với `npx ruflo@latest init` trong một dự án thử, giao một việc nhỏ, rồi mở `/ruflo` để xem nó làm gì trước khi dùng cho công việc thật.

## 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 dùng và sửa tự do. Tư liệu không nói gì về chi phí của Claude Code, Codex hay các nhà cung cấp mô hình mà bạn dùng cùng Ruflo. Plugin ruflo-cost-tracker có thể giúp theo dõi token và đặt ngân sách.

### Cài Ruflo bằng lệnh nào?

Trong thư mục dự án, chạy `npx ruflo@latest init`, rồi mở lại Claude Code ở cùng thư mục. Nếu muốn thiết lập theo kiểu hỏi đáp, README ghi có `npx ruflo@latest init wizard`. Cần Node 20 trở lên.

### Ruflo có cần GPU không?

Tư liệu không nêu yêu cầu GPU cho Ruflo. Chỉ có plugin ruflo-ruvector được mô tả là tìm kiếm tăng tốc GPU, và đó là tùy chọn riêng. Với yêu cầu phần cứng cụ thể, bạn nên xem thêm trong tài liệu của repo.

### Dùng được với Codex hay chỉ Claude Code?

Dùng được cả hai. README ghi Codex và các client MCP khác trỏ tới lệnh `npx -y ruflo@latest mcp start`. Ngoài ra có tùy chọn `npx ruflo init --grok` cho Grok Build.

### Cách cài bằng plugin khác gì cách `npx ruflo init`?

Cách plugin không thêm file nào vào workspace, chỉ cho lệnh slash, vài skill và định nghĩa agent; MCP server chỉ có khi cài ruflo-core, và không có hook. Cách `npx ruflo init` cho đủ vòng lặp: 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon, đổi lại ghi thêm file vào dự án.

### Claude có thể tự làm bậy trên bảng điều khiển không?

README nói bạn đặt giới hạn bằng mức quyền read, write, manage hoặc full, cùng chế độ ask hoặc auto. Mặc định hiện là read + ask. Hành động mạng, chi tiêu và phá hủy vẫn cần xác nhận kể cả khi để auto, và có nút Take back control để thu quyền.

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

Tư liệu không nêu rõ hệ điều hành được hỗ trợ. Điều kiện duy nhất được ghi là Node 20 trở lên, và các lệnh đều dựa trên npx. Bạn nên thử trên một dự án nhỏ trước, hoặc xem thêm tài liệu trong repo.
