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

> ruflo (tên cũ là Claude Flow) là một “harness”, tức lớp công cụ bọc quanh Claude Code và Codex. Nó thêm agent chuyên biệt, swarm nhiều agent phối hợp, bộ nhớ qua các phiên và MCP server. Cài chỉ cần một lệnh npx trong thư mục dự án, yêu cầu Node 20 trở lên.

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

ruflo là một “harness” (bộ khung điều phối) cho Claude Code và Codex. Nói đơn giản: mô hình AI lo việc viết, còn ruflo cho nó thêm công cụ, bộ nhớ, vòng lặp và các giới hạn kiểm soát để làm việc có tổ chức hơn. Repo này trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, và hiện có khoảng 81.582 sao cùng 9.607 fork trên GitHub.

Vấn đề nó giải quyết khá quen thuộc. Khi giao một việc lớn cho một AI duy nhất, bạn phải tự chia việc, tự nhắc lại bối cảnh, và sang phiên mới thì AI quên sạch. ruflo cho phép nhiều agent chia nhau việc theo kiểu “swarm” (đàn), nhớ lại kinh nghiệm từ các việc trước, và chạy ngầm trong Claude Code để bạn cứ dùng như bình thường.

Ai nên dùng? Lập trình viên đã quen Claude Code hoặc Codex và muốn thêm một tầng phối hợp agent. Người mới cũng thử được, vì README nói rõ: sau khi chạy `init`, bạn chỉ cần dùng Claude Code như thường, hệ thống hook sẽ tự định tuyến tác vụ ở phía sau. Điểm đáng giá nhất là cài chỉ với một lệnh, và có “bảng điều khiển” (console) để theo dõi agent, token và chi phí ngay cạnh Claude Code.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là lớp điều phối bọc quanh Claude Code và Codex: thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên làm việc, hook và MCP server 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 nhóm tính năng chính, theo đúng những gì README mô tả.

**Nhiều agent chuyên biệt làm việc như một đội.** README ghi bản cài bằng CLI cho bạn 98 agent, hơn 60 lệnh và 30 skill. Lợi ích thực tế: thay vì một AI làm tất cả, bạn có thể yêu cầu một “swarm” chia việc, ví dụ người tìm rủi ro, người viết test, người tóm tắt.

**Bộ nhớ qua nhiều phiên.** Agent nhớ lại kinh nghiệm và các mẫu làm việc thành công từ trước. Với bạn, điều này nghĩa là đỡ phải giải thích lại dự án mỗi lần mở phiên mới. README có lưu ý: phần học cục bộ cần embedding và các module học đã cấu hình, nên đừng hiểu là “tự thông minh lên” không cần cài gì.

**Hook tự định tuyến.** Sau khi `init`, hook sẽ chuyển tác vụ cho đúng agent và học từ các lần làm tốt. Bạn không cần học hết 406 công cụ MCP hay 61 lệnh CLI mà README nhắc tới.

**Bảng điều khiển trong Claude Code.** Plugin `ruflo-console` cho bạn theo dõi workflow, agent, mô hình, token và chi phí. Bạn cũng xem được log và kết quả của từng lần chạy, tìm kiếm, phát lại, so sánh. Mở bằng lệnh `/ruflo`.

**Cho Claude điều khiển bảng điều khiển, 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`, và chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiền hoặc phá huỷ vẫn phải xác nhận kể cả ở chế độ `auto`.

**Hệ plugin lớn.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia theo nhóm: điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), học (intelligence, goals), kiểm thử (testgen, browser), bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker)… Bạn chỉ cài cái mình cầ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 với nhau; README mô tả là an toàn và không rò rỉ dữ liệu. Phần này dành cho nhu cầu nâng cao, người mới có thể bỏ qua.

**Hỗ trợ nhiều nền tảng.** Ngoài Claude Code, ruflo chạy với Codex và các MCP client khác, và README còn nhắc tới Grok Build.

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

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

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json` của repo. Các lệnh dùng `npx`, vốn đi kèm Node.
- **Claude Code** nếu bạn muốn dùng đường cài plugin. Đường này yêu cầu Claude Code **2.1.287 trở lên**. Lệnh cài plugin từ terminal cần Claude Code **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy lệnh `init`.

README chưa nói gì về hệ điều hành cụ thể, yêu cầu GPU hay dung lượng ổ đĩa, nên mình không đoán. Nếu bạn dùng Windows, hãy thử và xem phần Lỗi hay gặp bên dưới. Về tài khoản và API key: đoạn README mình có không nêu cụ thể, bạn hãy xem phần cấu hình trong repo nếu muốn dùng thêm nhà cung cấp mô hình khác.

```note
Các plugin “mods” chạy với quyền của tài khoản bạn và không bị cô lập (sandbox). README khuyên đọc mã nguồn trước khi cài. Đây là lưu ý đáng nghe, đặc biệt nếu bạn dùng máy có dữ liệu công việc.
```

## 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 (một lệnh `npx`), vì README gọi đây là cách dùng đầy đủ nhất.

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

### Mở terminal trong thư mục dự án

Lệnh `init` ghi file vào đúng thư mục bạn đang đứng, nên đây là chỗ người mới hay vấp nhất. Hãy mở terminal rồi `cd` vào thư mục dự án thật. Đừng chạy ở thư mục Desktop hay thư mục gốc ổ đĩa.

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

### Chạy lệnh init

Đây là lệnh chính theo README. Nó thêm agent, hook, bộ nhớ và MCP server của ruflo vào dự án. Theo bảng so sánh trong README, bạn sẽ thấy xuất hiện `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file helper và settings.

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

Nếu muốn thiết lập có hướng dẫn từng câu hỏi, README cho lệnh này:

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

Nếu bạn dùng Grok Build, README có cờ `--grok`, và thêm `--dry-run` để xem trước mà chưa ghi gì:

```bash
npx ruflo init --grok
```

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

Claude Code nhận cấu hình ruflo ở lần khởi động kế tiếp, nên hãy mở (hoặc mở lại) Claude Code trong cùng thư mục. Rồi gõ câu lệnh mẫu từ README:

```text
Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.
```

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

Đường này không thêm file nào vào dự án và cho bạn công cụ lõi, bảng điều khiển và các mod. Gõ các lệnh sau **bên trong Claude Code** (không phải 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
```

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

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

Lưu ý README nói rõ: đường plugin chỉ cho bạn lệnh gạch chéo và định nghĩa agent, không cài hook. Muốn đủ vòng lặp như tài liệu mô tả, dùng đường `npx ruflo@latest init`.

### Đường thay thế: Codex hoặc MCP client khác

Với Codex hay công cụ MCP khác, bạn không cần thiết lập dự án. Cấu hình client với **command** là `npx` và **arguments** như bên dưới. Hoặc chạy trực tiếp lệnh MCP:

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

```bash
npx -y ruflo@latest mcp start
```

### Chạy bảng điều khiển ngoài Claude Code

Bảng điều khiển cũng chạy độc lập trong terminal. Thêm `--plain` nếu muốn in ra một khung duy nhất để dùng trong script.

```bash
npx ruflo tui
```

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

README không đưa ra một dòng “thành công” cố định cho lệnh `init`, nên bạn kiểm tra bằng các dấu hiệu sau:

1. **Thư mục dự án có file mới.** Sau `npx ruflo@latest init`, hãy xem có `.claude/`, `.claude-flow/` và `CLAUDE.md` hay chưa (đây là danh sách README nêu cho bản cài CLI).
2. **Gõ `/ruflo` trong Claude Code.** Nếu bảng điều khiển mở ra, console đã hoạt động.
3. **Với đường plugin,** gõ `/plugin` để xem các mod có nằm trong dòng “active mods” hay không.
4. **Giao câu lệnh mẫu** ở trên và xem Claude Code có dùng swarm để rà soát dự án không.

Nếu `/ruflo` không hiện, thử `/reload-plugins` hoặc đóng rồi mở lại Claude Code.

## 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ả thực tế sẽ tuỳ dự án và mô hình bạn dùng, nên hãy xem đây là gợi ý để thử.

### Lập trình viên muốn rà soát một dự án cũ

Bạn vừa nhận một repo mà không ai còn nhớ rõ. Sau khi `init`, mở Claude Code và dán đúng câu lệnh mẫu của README: nhờ swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Kết quả bạn nhận được là một danh sách thay đổi để đọc lại, thay vì phải tự đi dò từng thư mục. Hãy xem lại các file test do agent viết trước khi giữ.

### Người dẫn dự án muốn theo dõi chi phí và tiến độ

Bạn giao nhiều việc cho agent và lo tốn token. Cài `ruflo-console` rồi mở `/ruflo` để xem workflow, agent, mô hình, token và chi phí cùng lúc. README cũng có plugin `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí. Kết quả: bạn nhìn thấy việc nào đang tốn nhiều trước khi hoá đơn tới.

> Agent = Model + Harness. Mô hình lo 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

### Thử cho Claude tạo “mission” trong bảng điều khiển

Đây là bài thực hành an toàn mà README gợi ý. Mở `/ruflo`, vào Settings → Claude control và chọn **write + ask**. Rồi nhờ Claude:

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

Claude mở trang Missions và đặt mục tiêu; bạn xác nhận thao tác tạo. Sau đó kiểm tra mục tiêu đã có trong Missions và Overview đã ghi lại hành động. README nhấn mạnh: tạo mission **không có nghĩa** tính năng đã được làm xong. Nếu muốn dừng, bấm **Take back control**.

### Người dùng Codex hoặc công cụ MCP khác

Bạn không dùng Claude Code mà dùng Codex. Trỏ client của bạn tới `npx -y ruflo@latest mcp start` như phần cài đặt ở trên. Kết quả: công cụ của ruflo xuất hiện như một MCP server trong client đó, mà không phải thêm file nào vào dự án.

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

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

**Lệnh `npx` báo lỗi hoặc báo phiên bản Node cũ.** Repo yêu cầu Node từ 20.0.0 trở lên. Hãy kiểm tra bằng `node --version` và nâng cấp Node nếu cần.

**Cài xong mà Claude Code không thấy gì.** README nói Claude Code nhận cấu hình ở lần khởi động kế tiếp. Hãy đóng hẳn và mở lại trong đúng thư mục đã chạy `init`. Với đường plugin, thử `/reload-plugins`.

**Lệnh `/plugin` không nhận hoặc lệnh cài plugin bị từ chối.** Đường plugin cần Claude Code từ 2.1.287, còn lệnh `claude plugin install` ở terminal cần 2.1.292. Hãy cập nhật Claude Code trước.

**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` và `agentic-flow`: cài từ cả hai marketplace sẽ khiến mod và lệnh nạp hai lần. Chỉ chọn một nơi.

**Claude làm thao tác bạn không muốn.** Hãy giữ mức mặc định read + ask, chỉ nâng quyền khi cần, và dùng **Take back control** để dừng. Mình cũng khuyên chạy thử ở một thư mục dự án không quan trọng trước, vì `init` ghi nhiều file vào dự án.

Nếu bạn dùng Windows và gặp lỗi lạ, README phần mình có chưa nói gì về hệ điều hành. Hãy xem mục Issues và thư mục docs trong repo.

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

**Điểm mạnh.** Một lệnh là cài xong. Giấy phép MIT, ngôn ngữ chính TypeScript, repo vẫn được cập nhật trong 3 tháng gần đây. Bạn có hệ plugin rộng, bảng điều khiển để nhìn thấy agent đang làm gì, và cơ chế phân quyền rõ ràng (read/write/manage/full, ask/auto). Nó hợp với việc lớn cần nhiều bước như rà soát, viết test, tài liệu.

**Giới hạn.** Quy mô khá lớn: hàng chục plugin, hàng trăm công cụ MCP, nên người mới dễ choáng. Bản cài đầy đủ thêm khá nhiều file vào dự án. README cũng tự thừa nhận vài chỗ: sơ đồ kiến trúc chỉ là khái niệm, các bản demo dùng dữ liệu mẫu và không chứng minh swarm đã làm xong việc thật hay bộ nhớ nhớ lại đúng. Mình cũng chưa thấy thông tin về chi phí token khi chạy nhiều agent cùng lúc, nên hãy theo dõi sát.

**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 nhỏ hay sửa một file, ruflo là thừa. Nếu bạn không muốn bất kỳ file nào thêm vào dự án, hãy thử đường plugin trước, rồi mới quyết định có cài bản đầy đủ không. Còn nếu bạn mới làm quen với AI lập trình, hãy dùng Claude Code thuần một thời gian rồi quay lại với ruflo khi bắt đầu thấy mình cần chia việc cho nhiều agent.

## 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 tự do. Tuy vậy, tư liệu mình có chưa nói về chi phí gọi mô hình AI. Chi phí đó phụ thuộc vào công cụ bạn dùng với ruflo, ví dụ Claude Code hoặc Codex.

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

Bạn cần Node.js từ 20.0.0 trở lên, vì các lệnh dùng npx. Nếu đi đường plugin thì cần Claude Code từ 2.1.287 trở lên. README chưa nêu yêu cầu GPU hay phần cứng khác.

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

Phần README mình có không nói rõ về hệ điều hành. Lệnh cài dùng npx nên về nguyên tắc cần Node 20 trở lên. Bạn nên thử trên dự án không quan trọng và xem mục Issues trong repo nếu gặp lỗi.

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

ruflo là lớp bọc quanh Claude Code. Nó thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook và MCP server. Bạn vẫn dùng Claude Code như bình thường, còn ruflo điều phối ở phía sau.

### Cài bằng npx init và bằng plugin khác nhau thế nào?

Cài bằng npx init cho bản đầy đủ: agent, lệnh, skill, MCP server, hook và daemon, đồng thời thêm file vào dự án. Cài bằng plugin không thêm file vào dự án nhưng chỉ có lệnh gạch chéo, một số skill và định nghĩa agent. README đánh giá bản npx phù hợp cho dùng thực tế hơn.

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

Bạn tự đặt mức quyền (read, write, manage, full) và chế độ duyệt (ask hoặc auto); mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiền hoặc phá huỷ vẫn cần xác nhận kể cả ở auto. Bạn có thể bấm Take back control để dừng.

### Dùng ruflo với Codex hay công cụ khác ngoài Claude Code đượ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òn nhắc tới Grok Build với cờ --grok.
