# Ruflo: điều phối nhóm 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ụ bao quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ và hook. Bạn dùng nó để Claude Code làm việc có tổ chức hơn trên dự án thật. 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-11-07 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-claude-code-codex-huong-dan-6

Ruflo là một "agent harness" (bộ khung điều phối agent) cho Claude Code và Codex. Hiểu đơn giản: mô hình AI thì viết code, còn Ruflo cung cấp phần xung quanh để nó làm việc được cả một dự án: công cụ, bộ nhớ, vòng lặp, các điều khiển và cách chia việc cho nhiều agent. Repo này trước đây có tên Claude Flow, hiện có khoảng 81.588 sao và 9.608 fork trên GitHub, giấy phép MIT.

Vấn đề nó giải quyết rất đời thường. Khi bạn giao cho Claude Code một việc lớn, mỗi phiên làm việc thường bắt đầu lại từ đầu, và bạn phải tự chia nhỏ việc. Ruflo thêm vào dự án các agent chuyên biệt, hook tự động định tuyến công việc, và bộ nhớ lưu lại kinh nghiệm giữa các phiên. Theo README, bạn vẫn dùng Claude Code như bình thường, còn Ruflo lo phần phối hợp phía sau.

Bạn nên đọc bài này nếu là lập trình viên (kể cả mới) đang dùng Claude Code hoặc Codex và muốn thử một hệ nhiều agent. Điểm đáng giá nhất là cách vào cửa rất nhẹ: một lệnh `npx ruflo@latest init` là đủ để bắt đầu. Bài này mình đi từ cài đặt, kiểm tra, đến vài tình huống dùng thật, và nói thẳng những chỗ README còn mơ hồ.

```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ớ qua các phiên, hook và máy chủ MCP chỉ bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README giới thiệu khá nhiều thứ. Mình chọn ra những phần có ích nhất cho người mới.

### Agent và swarm

Ruflo bổ sung hàng chục agent chuyên biệt (README ghi 98 agent ở đường cài CLI, ở phần khác ghi "100+"). Chúng có thể tự tổ chức thành "swarm", tức một nhóm agent chia việc cho nhau. Lợi ích thực tế: bạn đưa một yêu cầu lớn như "review cả repo", và việc được chia cho nhiều agent thay vì một agent làm tuần tự.

### Bộ nhớ qua các phiên

Ruflo có bộ nhớ vector để lưu và truy xuất lại những gì agent đã học. README mô tả hệ thống ghi nhớ giữa các phiên và dùng kinh nghiệm cũ để định tuyến việc sau tốt hơn. README cũng ghi rõ đây là "sơ đồ khái niệm": phần tìm kiếm vector cục bộ chạy được không cần LLM, nhưng vẫn cần embedding và các module học đã cấu hình.

### Hook tự động

Sau `init`, các hook sẽ tự định tuyến tác vụ và học từ những mẫu thành công. README nhấn mạnh bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI. Cứ dùng Claude Code như cũ.

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

Plugin `ruflo-console` cho bạn một "buồng lái": theo dõi workflow, agent, mô hình, token và chi phí. Bạn mở nó bằng `/ruflo` trong Claude Code. Bạn cũng có thể cho Claude điều khiển console, nhưng với giới hạn do bạn đặt: `read`, `write`, `manage` hoặc `full`, kèm chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask.

### Hệ plugin

README liệt kê 48 plugin (cộng 3 plugin bên ngoài) theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), học tập, chất lượng code (testgen, browser, docs), bảo mật (security-audit, aidefence), DevOps (cost-tracker, observability)... Bạn cài lẻ từng cái, không bắt buộc cài hết.

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

Ruflo có federation (agent ở các máy khác nhau phối hợp an toàn), chạy được với Codex và các MCP client khác, và có tuỳ chọn cho Grok Build. Người mới chưa cần đến phần này, nhưng nên biết là có.

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

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

- **Node.js 20.0.0 trở lên** (package.json yêu cầu `>=20.0.0`). Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn muốn dùng cách chính. Nếu cài bằng plugin, cần Claude Code **2.1.287 trở lên**; lệnh `claude plugin install` từ terminal cần **2.1.292 trở lên**.
- Hoặc **Codex / một MCP client khác** nếu bạn không dùng Claude Code.
- Một thư mục dự án để chạy `init`.

README không nêu rõ yêu cầu hệ điều hành, phần cứng hay API key cụ thể cho việc cài. Riêng việc agent gọi tới nhà cung cấp mô hình nào thì phụ thuộc cấu hình của bạn, README chưa nói chi tiết trong phần mình có. Chi phí token phát sinh theo tài khoản Claude/Codex của bạn.

```note
Mod và plugin 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 code trước khi cài. Với tính năng "Claude control", đừng nâng mức quyền lên cao khi chưa cần.
```

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

Có ba đường chính. Mình khuyên người mới đi đường đầu tiên.

```steps
- Mở terminal đúng chỗ | Vào thư mục dự án của bạn
- Chạy init | npx ruflo@latest init
- Khởi động lại Claude Code | Mở lại Claude Code trong cùng thư mục
- Thử lệnh /ruflo | Mở bảng điều khiển để kiểm tra
```

### Mở terminal trong 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 trong dự án cần dùng. Trên Windows, bạn có thể mở PowerShell rồi dùng `cd`. Ví dụ:

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

### Chạy lệnh init

Lệnh này thêm agent, hook, bộ nhớ và máy chủ MCP của Ruflo vào dự án. README nói đường cài CLI tạo ra các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng các file hỗ trợ và cài đặt.

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

Nếu muốn thiết lập theo kiểu hỏi đáp từng bước, README cho lệnh này:

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

### Mở lại Claude Code

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận các thành phần mới ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code, hãy đóng rồi mở lại.

### 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, nhưng chỉ cho bạn công cụ lõi, console và mod (nhẹ hơn đường `init`). 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
```

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

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

Bảng so sánh trong README cho thấy hai đường khác nhau khá nhiều: plugin thì "zero file" trong dự án và không cài hook; còn `npx ruflo init` mới cho vòng lặp đầy đủ (98 agent, hơn 60 lệnh, 30 skill, máy chủ MCP, hook, daemon). README gọi đường `init` là phù hợp để dùng thật.

### Cách khác: dùng với Codex hoặc MCP client khác

Không cần thiết lập dự án. Trong phần cấu hình MCP của công cụ, đặt **command** là `npx` và **arguments** là:

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

README cũng nói bạn có thể gõ trực tiếp `npx -y ruflo@latest mcp start` để khởi động máy chủ MCP.

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

Console chạy được riêng, 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

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

- Sau `npx ruflo@latest init`, trong thư mục dự án xuất hiện `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Mở lại Claude Code, gõ `/ruflo` thì bảng điều khiển hiện ra.
- Nếu cài bằng plugin, mở `/plugin` và xem dòng "active mods" có tên các plugin bạn vừa cài.
- Trong console, lệnh `/ruflo market` mở Plugin Catalog: danh sách plugin, mod và skill, có nút cài, bật, tắt, cập nhật (mỗi thao tác đều hỏi xác nhận).

Nếu bạn không thấy gì sau khi cài, hãy kiểm tra lại: đã khởi động lại Claude Code chưa, và có đang đứng đúng thư mục dự án không.

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

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

### Dev nhận repo lạ và muốn rà nhanh

Bạn vừa nhận một dự án chưa quen. Sau khi `init` và mở lại Claude Code, bạn dán đú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.
```

Yêu 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. Bạn nhận được một bản rà soát có tổ chức thay vì phải tự chia việc. Hãy đọc lại các test được sinh ra trước khi tin.

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

### Người quản lý muốn nhìn tiến độ và chi phí

Bạn không code nhiều nhưng muốn biết agent đang làm gì và tốn bao nhiêu token. Bạn cài `ruflo-console`, mở `/ruflo` và xem workflow, agent, mô hình, token và chi phí cạnh Claude Code. README còn nói bạn có thể mở log và kết quả của 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. Plugin `ruflo-cost-tracker` cũng được mô tả là theo dõi token, đặt ngân sách và cảnh báo chi phí.

### Để Claude tự thao tác console, nhưng có giới hạn

README có một bài thử từng bước:

1. Cài console, mở `/ruflo`, vào **Settings → Claude control** và chọn **write + ask**.
2. Nhập yêu cầu cụ thể: "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ờ trong console.
4. Kiểm tra mục Missions có mục tiêu mới và mục Overview ghi lại hành động.
5. Bấm **Take back control** bất cứ lúc nào để dừng công cụ console của Claude.

Lưu ý README nhắc rõ: tạo mission không có nghĩa là tính năng đã được viết xong. Nó chỉ là bước đặt mục tiêu.

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

Nếu bạn dùng Codex, bạn không phải chuyển sang Claude Code. Chỉ cần khai báo máy chủ MCP với `npx -y ruflo@latest mcp start` như phần cài đặt. Khi đó công cụ của bạn gọi được các công cụ MCP của Ruflo (ví dụ bộ nhớ, swarm). Tư liệu mình có chưa mô tả quy trình chi tiết cho Codex, nên bạn nên xem thêm hướng dẫn trong thư mục docs của repo.

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

Một số lỗi dưới đây README nhắc trực tiếp, số khác là lỗi rất dễ gặp với loại công cụ này.

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

Nguyên nhân hay gặp là Node cũ. package.json yêu cầu Node 20 trở lên. Chạy `node --version` để kiểm tra, nâng cấp nếu thấp hơn rồi thử lại.

### Gõ /plugin marketplace add mà không nhận lệnh

Cách plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 cho lệnh `claude plugin install`). Hãy cập nhật Claude Code. Sau khi cài plugin, nhớ chạy `/reload-plugins`.

### Cài xong mà Claude Code không thấy gì

Hãy đóng hẳn Claude Code rồi mở lại trong đúng thư mục đã chạy `init`. Nếu bạn dùng đường plugin, kiểm tra `/plugin` xem plugin đã ở dòng active mods chưa.

### Plugin bị nạp hai lần

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ủa chính nó hoặc của ruflo), nếu bật cả hai thì mod và lệnh sẽ nạp hai lần. Hãy gỡ một bên.

### Claude từ chối thao tác trong console

Đây là hành vi có chủ đích. Hành động vượt mức quyền bạn đặt sẽ bị từ chối, và các thao tác mạng, chi tiêu, phá huỷ vẫn cần xác nhận kể cả ở chế độ `auto`. Nếu cần, nâng mức quyền một cách có ý thức, hoặc tự làm thao tác đó.

### Lo ngại về file được thêm vào dự án

Đường `init` thêm nhiều file vào dự án. Hãy chạy trên một nhánh hoặc dự án thử, và có commit sạch trước đó để dễ xem file nào mới sinh ra. Với Grok, README có cờ `--dry-run` để xem trước. Cờ này được ghi cho lệnh `init --grok`, nên đừng tự suy ra là mọi lệnh đều có.

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

**Điểm mạnh.** Vào cửa dễ (một lệnh), giấy phép MIT, được cập nhật gần đây, có cả đường cài nhẹ bằng plugin lẫn đường đầy đủ. Hệ sinh thái rộng: agent, bộ nhớ, console, bảo mật, theo dõi chi phí. README cũng trung thực ở vài chỗ, ví dụ ghi rõ bản demo dùng dữ liệu mẫu và chưa chứng minh việc swarm hoàn thành công việc thật hay việc nhớ lại bộ nhớ.

**Giới hạn.** Bề mặt rất lớn (hàng trăm công cụ MCP, hàng chục plugin), người mới dễ choáng. Đường `init` ghi nhiều file vào dự án. Mod không chạy trong sandbox, nên bạn phải tự đọc code. Tư liệu mình có chưa nói rõ hệ điều hành được hỗ trợ, và chưa có số liệu đo hiệu quả so với dùng Claude Code đơn thuần.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code viết vài đoạn code nhỏ, hoặc muốn một công cụ ít file và ít khái niệm, thì dùng Claude Code trơn là đủ. Nếu bạn tò mò mà chưa chắc, hãy thử đường plugin trước (không thêm file nào vào dự án), rồi mới lên đường `init` khi thấy hợp.

## 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 agent vẫn gọi tới mô hình AI qua tài khoản Claude hoặc Codex của bạn, nên chi phí token phát sinh theo gói của bạn. README có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

### Ruflo khác gì dùng Claude Code trơn?

Theo README, Ruflo là lớp bao quanh Claude Code và Codex, thêm agent chuyên biệt, swarm, bộ nhớ giữa các phiên, hook và máy chủ MCP. Bạn vẫn dùng Claude Code như bình thường, còn Ruflo phối hợp phía sau. Tư liệu chưa có số đo cụ thể về mức cải thiện.

### Cần cài gì trước khi dùng?

Cần Node.js 20 trở lên và Claude Code (hoặc Codex/một MCP client). Nếu cài bằng plugin thì cần Claude Code 2.1.287 trở lên. README không nêu yêu cầu GPU cho đường cài cơ bản.

### Cài nhanh nhất như thế nào?

Mở terminal trong thư mục dự án, chạy npx ruflo@latest init, rồi mở lại Claude Code. Sau đó giao một việc cụ thể, ví dụ nhờ swarm review repo và viết test cho module rủi ro nhất.

### Dùng với Codex được không?

Được. README nói Codex và các MCP client khác hoạt động bằng cách trỏ tới lệnh npx với tham số -y, ruflo@latest, mcp, start. Bạn không cần thiết lập dự án.

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

Tư liệu mình có chưa nêu rõ 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 thêm tài liệu trong repo để chắc chắn.

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

README mô tả cơ chế giới hạn: 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. Thao tác mạng, chi tiêu và phá huỷ luôn cần xác nhận, và bạn có thể bấm Take back control để dừng. Mod và plugin thì không bị sandbox, nên cần đọc code trước khi cài.
