# 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à một agent meta-harness cho Claude Code và Codex, thêm vào dự án các agent chuyên biệt, bộ nhớ, hook và MCP server để nhiều agent phối hợp theo bầy (swarm). Bạn dùng nó để giao việc lớn cho Claude Code mà vẫn có kiểm soát. Cài đặt 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-05-01 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-ai-agent-claude-code-codex-huong-dan-19

Ruflo là một "agent meta-harness" cho Claude Code và Codex: một lớp công cụ bao quanh mô hình AI, giúp nó có thêm agent chuyên biệt, bộ nhớ, vòng lặp và các chốt kiểm soát để làm việc thật sự, thay vì chỉ trả lời từng câu. Repo trước đây có tên Claude Flow, do Reuven Cohen (rUv) xây dựng, viết chủ yếu bằng TypeScript, giấy phép MIT. Hiện có khoảng 81588 sao và 9608 fork trên GitHub.

Tác giả giải thích bằng một công thức ngắn: Agent = Model + Harness. Mô hình lo phần viết. Harness lo phần còn lại: đưa công cụ, nhớ ngữ cảnh giữa các bước, chạy vòng lặp, đặt giới hạn. Ruflo là phần harness đó. Sau khi cài, bạn vẫn dùng Claude Code như bình thường, còn việc chọn agent, chia việc và ghi nhớ kinh nghiệm được hệ thống làm ngầm.

Repo hợp với lập trình viên đã dùng Claude Code và muốn giao những việc nhiều bước (rà soát code, viết test, tóm tắt thay đổi). Người làm văn phòng, kinh doanh cũng thử được nếu có người cạnh bên cài giúp lần đầu. Điểm đáng giá nhất là cài chỉ bằng một lệnh, có bảng điều khiển (console) để xem agent đang làm gì, và bạn tự đặt mức quyền cho Claude.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là lớp "harness" bao quanh Claude Code và Codex: thêm agent, bộ nhớ, hook và MCP server để nhiều agent phối hợp làm việc, cài bằng một lệnh.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Tư liệu của repo khá dài và có nhiều thứ. Bạn không cần học hết. README nói thẳng: bạn không phải học 406 công cụ MCP hay 61 lệnh CLI; sau `init`, cứ dùng Claude Code như bình thường. Dưới đây là những phần đáng biết nhất.

- **Swarm (bầy agent).** Nhiều agent tự tổ chức, chia nhau việc thay vì một agent làm tất cả. Với việc lớn như rà soát cả repo, cách này giúp mỗi agent tập trung một mảng.
- **Kho agent dựng sẵn.** Cài theo đường CLI, bạn nhận 98 agent, hơn 60 lệnh và 30 skill (số liệu trong bảng so sánh của README). Bạn không phải tự viết từng agent.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ được kinh nghiệm giữa các lần làm việc. README mô tả phần này là vòng học khái niệm: truy xuất vector cục bộ có thể chạy 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`, hook sẽ định tuyến tác vụ và học từ những mẫu làm việc thành công, chạy nền, bạn không phải gọi tay.
- **Console (buồng lái) trong Claude Code.** Theo dõi workflow, agent, model, token và chi phí ngay cạnh Claude Code. Bạn xem được nhật ký và kết quả 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 console nhưng bạn đặt giới hạn.** Bật Settings → Claude control rồi chọn mức `read`, `write`, `manage` hoặc `full`, cùng chế độ phê duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các thao tác mạng, tốn tiền hoặc phá huỷ vẫn phải xác nhận kể cả ở chế độ `auto`.
- **48 plugin cài riêng.** Gồm nhóm điều phối (swarm, autopilot, workflows), bộ nhớ (agentdb, rag-memory), kiểm thử (testgen, browser), bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker) và nhiều nhóm khác. Bạn chỉ cài cái cần.
- **Dùng được với Codex và MCP client khác.** Chỉ cần trỏ client tới máy chủ MCP của Ruflo.
- **Federation.** Agent trên các máy khác nhau liên lạc với nhau. Đây là phần nâng cao, người mới có thể bỏ qua.

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

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

- **Node.js từ 20.0.0 trở lên**, vì `package.json` yêu cầu `>=20.0.0`. Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn đi theo đường chính. Riêng đường chỉ cài 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**.
- **Một thư mục dự án** để chạy `init`. Lệnh này thêm file vào chính thư mục đó.
- Nếu dùng Codex hoặc MCP client khác: client đó phải cho cấu hình một lệnh ngoài (command và arguments).

Tư liệu không nêu hệ điều hành bắt buộc, không nêu yêu cầu GPU, và không nói rõ có cần khoá API riêng hay không (bạn vẫn cần tài khoản dùng được Claude Code hoặc Codex). Các mục này chưa có thông tin rõ trong phần README mình đọc được.

```note
Mod của Ruflo chạy với quyền tài khoản của bạn và không bị đóng khung (sandbox). README khuyên đọc code trước khi cài. Hãy giữ mức quyền Claude control ở read + ask lúc mới thử.
```

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

README có ba đường: cài đầy đủ bằng `npx`, chỉ cài plugin trong Claude Code, hoặc nối qua MCP cho Codex. Người mới nên chọn đường đầu.

```steps
- Mở terminal trong thư mục dự án | Vào đúng thư mục bạn muốn Ruflo làm việc
- 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ó nạp cấu hình mới
- Giao thử một việc thật | Gõ câu lệnh mẫu để Claude dùng swarm
- (Tuỳ chọn) Cài plugin console | Dùng /plugin trong Claude Code để có buồng lái /ruflo
```

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

Lệnh `init` ghi file vào thư mục hiện tại, nên bước này rất quan trọng. Trên Windows, bạn có thể mở PowerShell rồi đi tới thư mục dự án. Nếu dự án nằm trên GitHub và bạn chưa tải về, hãy clone trước (thay `<chủ>/<repo>` bằng dự án của bạn):

```bash
git clone https://github.com/<chủ>/<repo>.git
cd <repo>
```

Người mới hay vấp ở chỗ chạy lệnh ngoài thư mục dự án, khiến file Ruflo nằm sai chỗ.

### Chạy lệnh init

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

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

`npx` tải và chạy Ruflo mà không cần cài toàn cục. `init` thêm vào dự án các agent, hook, bộ nhớ và MCP server. Theo bảng so sánh của README, thư mục của bạn sẽ có thêm `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và file cài đặt. Nếu muốn cấu hình tương tác từng bước, README ghi:

```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ẽ nạp cấu hình ở lần khởi động kế tiếp, nên nếu nó đang mở sẵn, hãy đóng và mở lại. Rồi thử 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.
```

Bạn có thể viết bằng tiếng Việt, nhưng câu mẫu trên là nguyên văn README nên chắc chắn đúng ý.

### Cài console qua plugin (tuỳ chọn)

Đường này cho bạn buồng lái trong Claude Code mà không thêm file nào vào dự án. Gõ từng dòng trong chính Claude Code (không phải trong 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 muốn cài từ terminal (Claude Code 2.1.292 trở lên):

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

Lưu ý README nói rõ đây là hai đường khác nhau. Plugin cho bạn lệnh gạch chéo và vài skill, không có hook. Đường `npx ruflo@latest init` mới cho trọn bộ vòng lặp (agent, hook, daemon, MCP server).

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

Không cần cài vào dự án. Cấu hình client với **command** là `npx` và **arguments** là `["-y", "ruflo@latest", "mcp", "start"]`. README cũng viết gọn là trỏ client tới lệnh `npx -y ruflo@latest mcp start`.

### Chạy console trong terminal thường

Console 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, tiện cho script.

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

README không đưa ra một dòng "cài thành công" cố định, nên mình chỉ nêu những dấu hiệu có trong tư liệu:

1. **Thư mục dự án có file mới.** Sau `npx ruflo@latest init`, bạn thấy `.claude/`, `.claude-flow/` và `CLAUDE.md`.
2. **Console mở được.** Trong Claude Code, gõ `/ruflo`. Nếu bạn cài plugin, mở `/plugin` và kiểm tra các mod xuất hiện ở dòng "active mods".
3. **Terminal UI lên hình.** Chạy `npx ruflo tui` và thấy giao diện console.
4. **Thử nhiệm vụ nhỏ.** README gợi ý: đặt Claude control ở write + ask, rồi nhờ "Create a mission to add a dark mode toggle. Show me the mission and its status." Bạn xác nhận hành động tạo, rồi kiểm tra mục Missions có mục tiêu đó và Overview ghi lại hành động. Lưu ý: tạo mission không có nghĩa tính năng đã được viết.

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

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

### Rà soát một repo cũ và viết test cho chỗ rủi ro nhất

Bối cảnh: bạn là lập trình viên mới nhận một dự án không có test. Bạn chạy `npx ruflo@latest init` trong thư mục dự án, mở lại Claude Code và 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 xem code, chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Bạn đọc lại tóm tắt và chạy test để kiểm chứng.

> Giao cho AI việc lớn thì được, nhưng hãy đặt giới hạn trước và đọc kết quả sau.
>
> — Ông T

### Theo dõi chi phí và agent bằng console

Bối cảnh: bạn lo AI chạy lâu sẽ tốn token mà không biết nó đang làm gì. Cài `ruflo-console` rồi gõ `/ruflo`. Console cho bạn xem workflow, agent, model, token và chi phí ngay cạnh Claude Code, đồng thời mở nhật ký từng agent để tra lỗi. Nếu muốn đặt ngân sách và cảnh báo, README có plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí).

### Để Claude tự thao tác console trong giới hạn

Bối cảnh: bạn muốn Claude tự tạo và quản lý đầu việc, nhưng không muốn nó tự ý làm gì tốn tiền. Vào Settings → Claude control, chọn `write` và `ask`. Rồi nhờ:

```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 bấm xác nhận hành động tạo. Kiểm tra Missions và Overview. Nếu thấy nó làm gì không ưng ý, bấm **Take back control** để dừng ngay các công cụ console của Claude; lệnh gọi sau đó sẽ bị từ chối cho đến khi bạn trả quyền lại.

### Nối Ruflo vào Codex hoặc công cụ MCP khác

Bối cảnh: nhóm bạn dùng Codex chứ không chỉ Claude Code. Trong phần cấu hình MCP của client, đặt command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`. Client sẽ khởi động máy chủ MCP của Ruflo và dùng các công cụ của nó. Muốn thiết lập theo dự án có hướng dẫn từng bước, chạy `npx ruflo@latest init wizard`.

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

Tư liệu README không có mục xử lý sự cố, nên các mục dưới đây là những lỗi rất dễ xảy ra với loại công cụ này, kèm hướng xử lý an toàn.

### Claude Code không thấy agent, hook hay lệnh `/ruflo`

Nguyên nhân hay gặp: Claude Code đang mở từ trước. README nói nó nạp cấu hình ở lần khởi động kế tiếp. Hãy đóng và mở lại trong đúng thư mục đã chạy `init`. Nếu cài plugin, chạy `/reload-plugins`. Mở `/plugin` để kiểm tra plugin đã bật.

### Báo lỗi vì phiên bản Node quá cũ

`package.json` yêu cầu Node 20 trở lên. Kiểm tra bằng `node --version`. Nếu thấp hơn, nâng cấp Node rồi chạy lại lệnh `npx`.

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

Đường plugin cần Claude Code 2.1.287 trở lên, và lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code trước. Cũng nhớ gõ các lệnh `/plugin` bên trong Claude Code, không phải trong terminal thường.

### Tool bị gọi sai tên khi trộn hai đường cài

README cảnh báo: plugin `ruflo-core` đăng ký công cụ dưới tên như `mcp__plugin_ruflo-core_ruflo__memory_store`, khác với tên ngắn của đường CLI (`memory_store`, `swarm_init`, `agent_spawn`). Muốn trọn bộ vòng lặp với tên theo đường CLI thì dùng `npx ruflo@latest init`. Đừng trộn hai cách khi bạn chưa hiểu rõ.

### Plugin bên ngoài bị nạp hai lần

Với một số plugin bên ngoài (như `agentic-qe-fleet`, `agentdb`, `agentic-flow`), README dặn chỉ cài từ một marketplace. Cài từ cả hai nơi thì mod và lệnh sẽ nạp đôi. Chọn một nơi và gỡ bản còn lại.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có giấy phép MIT. Repo còn được cập nhật trong ba tháng gần đây. Cộng đồng lớn (khoảng 81588 sao). Có console để nhìn thấy agent làm gì, và bạn tự đặt mức quyền, với các thao tác mạng, tốn tiền, phá huỷ luôn cần xác nhận. Dùng được với Claude Code, Codex và MCP client khác.

**Giới hạn.** Tư liệu khá nhiều thuật ngữ và nhiều thành phần (48 plugin, hàng trăm công cụ), người mới dễ choáng. Đường `init` thêm khá nhiều file vào dự án. Mod chạy với quyền tài khoản của bạn, không sandbox. README cũng nói rõ các đoạn demo dùng dữ liệu mẫu và không chứng minh việc swarm hoàn thành công việc thật hay bộ nhớ nhớ lại đúng; phần học là "khái niệm". Hãy tự kiểm chứng kết quả trên dự án của mình.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần Claude Code làm vài việc nhỏ, cứ dùng nó trơn, chưa cần thêm lớp điều phối. Nếu bạn muốn thử nhẹ, chỉ cài `ruflo-core` và một hai plugin, không thêm file vào dự án. Còn nếu không dùng Claude Code hay Codex thì repo này không phải công cụ dành cho bạn.

Lời khuyên của mình: thử trên một dự án nhỏ hoặc bản sao, giữ Claude control ở read + ask, chạy câu lệnh mẫu của README, rồi mới nâng quyền 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 bạn dùng mã nguồn tự do. Tuy vậy, Ruflo chạy trên Claude Code hoặc Codex, nên chi phí dùng các mô hình đó vẫn tính riêng theo tài khoản của bạn. Tư liệu có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

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

Tư liệu README mình đọc được không nêu rõ danh sách hệ điều hành hỗ trợ. Yêu cầu được ghi rõ là Node từ 20.0.0 trở lên và lệnh npx. Bạn nên thử trên một thư mục nhỏ trước và xem trang tài liệu của repo nếu gặp lỗi.

### Cần GPU không?

Tư liệu không nêu yêu cầu GPU cho đường cài chính. Có plugin ruflo-ruvector được mô tả là tìm kiếm tăng tốc bằng GPU, nhưng đó là plugin riêng và không bắt buộc.

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

Ruflo là lớp harness bao quanh Claude Code: thêm agent chuyên biệt, bộ nhớ qua nhiều phiên, hook định tuyến tác vụ, console theo dõi và khả năng chia việc cho nhiều agent. Bạn vẫn dùng Claude Code như bình thường, phần điều phối chạy nền.

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

Có, nếu đi theo đường npx ruflo@latest init: README nói nó thêm .claude/, .claude-flow/, CLAUDE.md và các file hỗ trợ. Đường chỉ cài plugin trong Claude Code thì không thêm file nào vào workspace. Dùng init với tùy chọn --dry-run chỉ được README nêu cho Grok Build, nên với các đường khác hãy thử trên bản sao trước.

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

Bạn tự đặt 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 vượt mức quyền bị từ chối, và các thao tác mạng, tốn tiền hay phá huỷ vẫn cần xác nhận kể cả khi để auto. Bạn cũng bấm Take back control để dừng ngay.

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

Được. README ghi: cấu hình client với command là npx và arguments là ["-y", "ruflo@latest", "mcp", "start"]. Nếu muốn thiết lập theo dự án, chạy npx ruflo@latest init wizard.
