# 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 là một agent meta-harness cho Claude Code và Codex. Nó thêm các agent chuyên biệt, bộ nhớ qua nhiều phiên, hook và MCP server vào dự án của bạn để AI làm việc theo nhóm. Cài khá dễ: cần Node 20 trở lên và chạy một lệnh `npx ruflo@latest init` trong thư mục dự án.

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

Ruflo là một **bộ khung điều phối (harness)** đặt quanh Claude Code và Codex. Model AI lo việc viết, còn Ruflo cung cấp công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát để AI làm việc như một nhóm thay vì từng phiên rời rạc. Repo có tên cũ là Claude Flow, hiện có khoảng 81.600 sao và 9.600 fork trên GitHub, giấy phép MIT.

Nếu bạn đã dùng Claude Code và thấy mỗi phiên làm việc đều phải giải thích lại từ đầu, Ruflo nhắm đúng chỗ đó. Sau khi cài, bạn vẫn dùng Claude Code như bình thường. Phần hook của Ruflo tự định tuyến tác vụ, học từ những lần làm thành công và phối hợp các agent ở phía sau.

Điểm đáng giá nhất là cách cài rất gọn: một lệnh `npx ruflo@latest init` trong thư mục dự án, rồi mở lại Claude Code. Ngoài ra còn có bảng điều khiển (console) hiển thị agent, token và chi phí ngay cạnh Claude Code. Bài này hướng dẫn từ cài đặt đến vài tình huống dùng thật, và nói rõ những chỗ bạn nên cẩn thận.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung (harness) bọc quanh Claude Code và Codex, thêm agent, bộ nhớ, hook và MCP server chỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README mô tả Ruflo bằng công thức: Agent = Model + Harness. Dưới đây là những phần mình thấy hữu ích nhất cho người mới.

- **Nhiều agent chuyên biệt làm việc theo nhóm (swarm).** README nêu hơn 100 agent chuyên biệt, tự tổ chức thành nhóm. Bạn chỉ cần nêu việc cần làm, ví dụ rà soát một repo rồi viết test, các agent tự chia việc.
- **Bộ nhớ tự học, nhớ qua nhiều phiên.** Ruflo lưu lại kinh nghiệm từ các tác vụ trước và đưa ngược vào việc định tuyến. README ghi rõ đây là sơ đồ khái niệm, và phần tìm kiếm vector cục bộ có thể chạy mà 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 định tuyến tác vụ ở nền. Bạn không phải học hết 406 công cụ MCP hay 61 lệnh CLI mà README liệt kê.
- **Console `/ruflo`.** Đây là cockpit để theo dõi workflow, agent, model, token và chi phí. Bạn mở nhật ký 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. Console còn chạy riêng được trong terminal bằng `npx ruflo tui`.
- **Claude control có giới hạn do bạn đặt.** Bạn cho phép Claude điều khiển console ở một trong bốn mức: `read`, `write`, `manage`, `full`, kèm chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các hành động dddùng mạng, tốn tiền hoặc phá huỷ vẫn phải xác nhận, kể cả khi để `auto`.
- **Hệ 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ử và chất lượng mã, bảo mật, DevOps. Ví dụ `ruflo-testgen` tìm test còn thiếu và tạo test, `ruflo-cost-tracker` theo dõi token và đặt ngân sách, `ruflo-docs` tạo và duy trì tài liệu.
- **Liên kết nhiều máy (federation).** Các agent trên máy khác nhau có thể nói chuyện với nhau mà README nói là không làm rò dữ liệu. Bạn có thể bỏ qua phần này lúc mới bắt đầu.
- **Dùng với Codex và client MCP khác.** Bạn trỏ client MCP vào `npx -y ruflo@latest mcp start`. README cũng có mục cho Grok Build với cờ `--grok`.

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

Phần này mình chỉ nêu những gì tư liệu nói:

- **Node.js 20 trở lên.** `package.json` của repo yêu cầu `>=20.0.0`. Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn dùng đường chính. Với đường cài chỉ bằng plugin, README yêu cầu Claude Code **2.1.287 trở lên**. Riêng lệnh `claude plugin install` chạy từ terminal cần **2.1.292 trở lên**.
- **Một thư mục dự án** để chạy `init`. Lệnh này ghi file vào chính thư mục đó.
- **Codex hoặc client MCP khác** nếu bạn không dùng Claude Code. README không nêu thêm yêu cầu nào khác.

Về tài khoản, API key hay phần cứng (GPU), phần README mình có không nói gì cụ thể. Bạn dùng Claude Code hay Codex thì cần tài khoản của công cụ đó như bình thường. Gói npm còn có tên `claude-flow` với lệnh CLI, nhưng README hướng dẫ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ị cô lập (sandbox). README khuyên đọc mã trước khi cài. Hãy giữ Claude control ở mức read hoặc write kèm ask, đừng vội nâng lên full.
```

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

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án bạn muốn dùng Ruflo
- Chạy init | Lệnh npx thêm agent, hook, bộ nhớ và MCP server vào dự án
- Mở 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 cho swarm làm, ví dụ rà soát repo
- (Tuỳ chọn) Cài plugin hoặc MCP | Chọn đường cài chỉ bằng plugin, hoặc cấu hình cho Codex
```

### 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 quan trọng. Người mới hay mở terminal ở thư mục khác rồi chạy lệnh, kết quả là file nằm sai chỗ. Trên Windows, bạn có thể mở PowerShell rồi dùng `cd` vào thư mục dự án. Nếu chưa có dự án, bạn lấy repo của mình về bằng `git clone`, rồi `cd` vào thư mục vừa tạo.

```bash
cd ten-thu-muc-du-an
```

### Chạy lệnh init

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

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

`npx` tải và chạy bản Ruflo mới nhất mà không cần cài toàn cục. Theo README, `init` thêm agent, hook, bộ nhớ và MCP server vào dự án. Bảng so sánh của README cho biết đường này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings trong dự án của bạn. Vì vậy nếu dự án đang dùng git, bạn nên xem lại danh sách file thay đổi sau khi chạy.

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

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

### Mở lại Claude Code

README nói Claude Code sẽ nhận agent và hook "ở lần khởi động tiếp theo". Vì thế nếu Claude Code đang mở, bạn hãy đóng đi và mở lại trong cùng thư mục. Bước này hay bị bỏ qua, rồi người dùng thắc mắc vì không thấy gì thay đổi.

### Giao một việc thật

Trong Claude Code, bạn gõ một yêu cầu cụ thể. README dùng đúng câu này làm ví dụ:

```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 mình khuyên bắt đầu với câu mẫu trên để chắc chắn khớp cách README mô tả.

### Tuỳ chọn: cài bằng plugin Claude Code (không thêm file vào dự án)

Đường này dành cho bạn muốn thử mà không để file nào trong dự án. README ghi rõ nó 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 muốn cài từ terminal (cần Claude Code 2.1.292 trở lên):

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

Lưu ý README so sánh hai đường: plugin thì "lite", chủ yếu là lệnh slash và định nghĩa agent. Đường `npx ruflo init` mới là vòng lặp đầy đủ với hook, daemon và MCP server, và README gọi đó là cách dùng cho sản xuất. Nếu có ý định dùng nghiêm túc, bạn nên chọn `init`.

### Tuỳ chọn: dùng với Codex hoặc client MCP khác

Không cần setup dự án. Trong phần cấu hình MCP của client, đặt **command** là `npx` và **arguments** như sau:

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

Tương đương dòng lệnh `npx -y ruflo@latest mcp start`. Mỗi client có chỗ nhập cấu hình khác nhau, README không hướng dẫn chi tiết từng client, nên bạn xem tài liệu của client đang dùng để biết ô nào điền gì.

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

README không đưa ra một dòng kết quả chuẩn cho lệnh `init`, nên mình chỉ nêu những dấu hiệu mà tư liệu có nhắc:

- **Với đường `init`:** mở lại Claude Code trong thư mục dự án và gõ `/ruflo`. README nói bạn bắt đầu bằng `npx ruflo init`, khởi động lại Claude Code, rồi gõ `/ruflo` để mở console. Trong thư mục dự án cũng xuất hiện `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- **Với đường plugin:** mở `/plugin` và xem các mod có nằm trong dòng "active mods" không. Trong console, `/ruflo market` mở Plugin Catalog để xem, cài, bật, tắt và cập nhật plugin (mỗi hành động đều hỏi bạn trước).
- **Chạy console riêng:** `npx ruflo tui` mở giao diện terminal không cần Claude Code. Thêm `--plain` nếu muốn in một khung hình cho script.

Cách thử chắc nhất là giao một tác vụ nhỏ như ví dụ ở trên rồi xem Claude Code có phối hợp agent và báo lại việc đã làm không.

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

Mình chỉ đưa các tình huống bám vào khả năng README mô tả. Kết quả thực tế phụ thuộc dự án và model bạn dùng.

### Dev rà soát một repo và bổ sung test

Bạn là lập trình viên vừa nhận một repo lạ và chưa biết sửa gì trước. Mở Claude Code trong thư mục repo, sau khi đã chạy `init`, rồi gõ 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.
```

Bạn nhận lại phần xác định module rủi ro nhất, các test mới và bản tóm tắt thay đổi. Hãy chạy lại test và đọc diff trước khi giữ kết quả.

> Bạn không cần học hết hàng trăm công cụ. Cài xong, cứ dùng Claude Code như mọi ngày, còn việc phối hợp để Ruflo lo ở phía sau.
>
> — Ông T

### Người mới theo dõi AI làm việc bằng console

Bạn không biết code nhưng muốn xem AI đang làm gì và tốn bao nhiêu. Cài `ruflo-console` rồi mở `/ruflo`. Đây là cockpit theo dõi workflow, agent, model, token và chi phí. Bạn có thể mở nhật ký agent, tìm kiếm, xem lỗi và phát lại. README cũng có kịch bản "tạo mission" từng bước:

1. Vào Settings → Claude control và chọn `write + ask`.
2. Nhờ Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status."
3. Xác nhận thao tác tạo khi console hỏi.
4. Kiểm tra mục Missions có mục tiêu mới và Overview có ghi lại hành động.

README nhấn mạnh việc tạo mission **không có nghĩa** tính năng đã được làm xong. Nó chỉ là bản ghi mục tiêu. Nếu cần dừng, bạn bấm **Take back control**.

### Chủ doanh nghiệp nhỏ kiểm soát chi phí token

Bạn thuê dev hoặc tự thử dùng AI cho nhiều việc và lo hoá đơn tăng. README liệt kê plugin `ruflo-cost-tracker`: theo dõi lượng token, đặt ngân sách và cảnh báo chi phí. Bạn cài như các plugin khác:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-cost-tracker@ruflo
/reload-plugins
```

Mình chỉ chắc về mô tả một dòng của README. Các tuỳ chọn cụ thể, README bản mình có chưa nêu, nên bạn đọc trang hướng dẫn của plugin trước khi đặt ngân sách.

### Nhóm nhỏ dùng Codex qua MCP

Nhóm bạn dùng Codex thay vì Claude Code. Bạn không cần chạy `init` mà cấu hình MCP với command `npx` và đối số như phần cài đặt ở trên. Khi đó Codex gọi được công cụ của Ruflo qua MCP. Nếu muốn thiết lập dự án có hướng dẫn, chạy `npx ruflo@latest init wizard`.

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

**Mở Claude Code rồi mà không thấy gì mới.** Thường do chưa khởi động lại sau `init`. Đóng Claude Code, mở lại ở đúng thư mục dự án rồi gõ `/ruflo`. Kiểm tra nữa là thư mục có `.claude/` và `CLAUDE.md` chưa.

**Lệnh `npx` báo lỗi hoặc không chạy.** Kiểm tra phiên bản Node bằng `node -v`. `package.json` yêu cầu Node 20 trở lên, nên bản cũ hơn có thể gây lỗi. Nâng Node lên rồi chạy lại.

**Lệnh `/plugin` hoặc `claude plugin install` không nhận.** Đường plugin cần Claude Code 2.1.287 trở lên, riêng lệnh từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code rồi thử lại.

**Cài plugin hai lần, lệnh bị nạp đôi.** README cảnh báo với các plugin ngoài như `agentic-qe-fleet`, `agentdb` và `agentic-flow`: chỉ nên cài từ **một** marketplace. Nếu bật từ cả hai nơi, mod và lệnh bị nạp hai lần. Bạn gỡ một bản đi.

**Gọi nhầm tên công cụ MCP giữa hai đường cài.** README giải thích plugin `ruflo-core` đăng ký công cụ với tên dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, còn đường CLI dùng tên trần như `memory_store`. Khi làm theo tài liệu, hãy chọn đúng một đường và dùng tên công cụ của đường đó.

**Claude từ chối thực hiện một thao tác trong console.** Đây thường là đúng thiết kế. Hành động vượt mức quyền bạn đặt bị từ chối, còn hành động dùng mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận. Muốn làm việc đó, bạn tự nâng quyền trong Settings, nhưng hãy cân nhắc trước khi chọn `full` hoặc `auto`.

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

**Điểm mạnh.** Cài đặt gọn bằng một lệnh. Tích hợp sẵn với Claude Code và Codex. Có bộ nhớ qua nhiều phiên, console để quan sát và hệ plugin rộng. Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây. README cũng thẳng thắn về giới hạn, ví dụ nói rõ các 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.

**Giới hạn.** Hệ thống rất 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 nên bắt đầu chỉ với `init` và một tác vụ nhỏ. Đường `init` thêm khá nhiều file vào dự án. Các mod không được sandbox. Về chi phí, README chưa nói Ruflo tốn thêm bao nhiêu token, nên bạn cần theo dõi bằng console khi chạy nhiều agent cùng lúc.

**Khi nên 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 file đơn giản, cứ dùng Claude Code thuần, không cần thêm tầng điều phối. Nếu muốn thử nhẹ, hãy chọn đường plugin chỉ cài `ruflo-core`. Khi đã quen và cần vòng lặp đầy đủ, hãy chuyển sang `npx ruflo@latest init`.

## 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. Ruflo chạy trên Claude Code hoặc Codex, nên chi phí dùng model vẫn tính theo tài khoản của các công cụ đó. README chưa nêu chi phí cụ thể.

### Cài Ruflo cần những gì?

Theo package.json, bạn cần Node.js 20 trở lên. Đường chính là chạy `npx ruflo@latest init` trong thư mục dự án rồi mở lại Claude Code. Riêng đường cài bằng plugin cần Claude Code 2.1.287 trở lên.

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

Tư liệu mình có không nêu yêu cầu GPU cho việc cài và dùng cơ bản. README có nhắc plugin ruflo-ruvector hỗ trợ tìm kiếm tăng tốc GPU, nhưng đó là plugin tuỳ chọn. Chưa có thông tin về cấu hình phần cứng tối thiểu.

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

README không có mục nào nói riêng về hệ điều hành. Các lệnh chính đều là `npx`, nên chỉ cần máy có Node.js 20 trở lên. Chưa có thông tin chính thức về những khác biệt riêng của Windows.

### 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 nhiều phiên, hook, MCP server và console theo dõi. Claude Code vẫn là nơi bạn làm việc, còn Ruflo điều phối ở phía sau.

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

Có. README nói Codex và các client MCP khác dùng được bằng cách trỏ tới `npx -y ruflo@latest mcp start`, với command là `npx` và các đối số `-y`, `ruflo@latest`, `mcp`, `start`. Bạn không cần setup dự án cho cách này.

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

README mô tả bạn tự chọn mức quyền (read, write, manage, full) và chế độ duyệt (ask hoặc auto). Mặc định hiện là read + ask. Hành động mạng, tốn tiền hoặc phá huỷ luôn cần xác nhận, và nút Take back control dừng ngay quyền điều khiển.
