# 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 (trước đây là Claude Flow) là một "harness" cho Claude Code và Codex. Nó thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên và MCP server vào dự án của bạn. Cài chỉ cần một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên.

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

Ruflo là một "agent harness" mã nguồn mở, bao quanh Claude Code và Codex. Hiểu đơn giản: model AI là người viết code, còn Ruflo là cái bàn làm việc đầy đủ đồ nghề đặt quanh người đó. Nó thêm công cụ, bộ nhớ, vòng lặp và các lớp kiểm soát để AI làm được việc dài hơi, thay vì chỉ trả lời từng câu một.

Repo giải quyết một vấn đề quen thuộc. Khi giao cho Claude Code một việc lớn, bạn phải tự chia nhỏ, tự nhắc lại bối cảnh, và mỗi phiên mới nó lại quên hết. Ruflo cho phép nhiều agent phối hợp thành một "swarm", nhớ lại kinh nghiệm giữa các phiên, và có bảng điều khiển để bạn theo dõi chuyện gì đang diễn ra.

Bài này dành cho lập trình viên mới, người đã dùng Claude Code và muốn nó làm được việc lớn hơn. Điểm đáng giá nhất là bạn không cần học hết hàng trăm công cụ. README nói rõ: sau khi chạy `init`, bạn cứ dùng Claude Code như bình thường, các hook sẽ tự định tuyến tác vụ và điều phối agent ở phía sau. Repo hiện có khoảng 81.588 sao và 9.608 fork, giấy phép MIT.

```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ỉ với một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những phần chính, nói theo lợi ích thực tế.

**Agent chuyên biệt và swarm.** Ruflo đưa vào hàng chục agent có vai trò riêng. README nêu con số 98 agent khi cài bằng CLI (và nhắc tới 100+ ở phần giới thiệu). Chúng được tổ chức thành swarm, tức là một nhóm cùng làm một việc. Lợi ích: bạn có thể giao "rà soát cả repo" thay vì từng file.

**Bộ nhớ qua nhiều phiên.** Agent có thể lưu và gọi lại kinh nghiệm, kể cả giữa các lần mở Claude Code khác nhau. README ghi phần 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. Đừng hiểu nó là phép màu.

**Hook tự động.** Sau `init`, hook sẽ định tuyến tác vụ và học từ các mẫu thành công. Bạn không phải gõ thêm lệnh gì.

**MCP server.** Ruflo chạy như một MCP server, nên Codex hoặc bất kỳ ứng dụng nào hỗ trợ MCP đều dùng được. README cũng nhắc tới Grok Build qua cờ `--grok`.

**Bảng điều khiển (console).** Đây là "buồng lái" cạnh Claude Code: theo dõi workflow, agent, model, token và chi phí. Bạn có thể mở log của từng agent, tìm kiếm, xem lại và so sánh các lần chạy. Bảng này cũng chạy được ở terminal thuần bằng `npx ruflo tui`.

**Kho plugin.** Có 48 plugin (cộng 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học, kiểm thử, bảo mật, theo dõi chi phí… 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-security-audit` quét lỗ hổng.

**Liên kết nhiều máy (federation).** Agent trên các máy khác nhau có thể trao đổi an toàn. Tính năng này dành cho người dùng nâng cao, người mới có thể bỏ qua.

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

Tư liệu của repo chỉ nêu một số điều kiện cụ thể:

- **Node.js 20.0.0 trở lên** (theo `package.json`). Lệnh `npx` đi kèm Node.
- **Claude Code** nếu bạn muốn dùng theo cách chính. Riêng đường cài chỉ bằng plugin, README yêu cầu Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` ngoài terminal cần bản **2.1.292 trở lên**.
- Codex hoặc ứng dụng MCP khác nếu bạn không dùng Claude Code.

README phần đã cung cấp không nói rõ về hệ điều hành, API key hay phần cứng. Mình sẽ không đoán. Nếu cần biết, hãy xem `docs/` và các file `README.md`, `CLAUDE.md` trong repo.

```note
Mod của Ruflo chạy với quyền tài khoản của bạn và không nằm trong sandbox. README khuyên đọc code trước khi cài. Hãy làm vậy, nhất là khi dùng trên máy có dữ liệu công việc.
```

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

```steps
- Mở terminal | Đứng trong thư mục dự án của bạn
- Chạy init | Gõ npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Mở lại Claude Code | Mở Claude Code ở cùng thư mục để nó nhận cấu hình mới
- Giao việc thật | Nhờ Claude Code dùng swarm của ruflo làm một việc cụ thể
- Mở console | Gõ /ruflo trong Claude Code để xem bảng điều khiển
```

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

Chỗ người mới hay vấp nhất là chạy lệnh sai thư mục. `init` ghi file vào dự án hiện tại, nên bạn phải đứng đúng trong thư mục dự án. Trên Windows, bạn có thể mở PowerShell rồi dùng `cd` tới thư mục đó.

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

### Chạy lệnh init

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

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

`npx` tải và chạy Ruflo mà không cần cài toàn cục. Lệnh `init` thêm agent, hook, bộ nhớ và MCP server vào dự án. README cho biết đường cài này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng các file hỗ trợ và cài đặt. Nếu dự án của bạn đã có `CLAUDE.md`, hãy sao lưu trước khi chạy.

Nếu muốn thiết lập có hỏi đáp từng bước, README có sẵn chế độ wizard:

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

### Mở lại Claude Code

Claude Code nhận cấu hình mới ở lần khởi động kế tiếp. Vì vậy hãy mở (hoặc khởi động lại) Claude Code trong cùng thư mục dự án. Nếu bạn đang để Claude Code mở từ trước, thay đổi sẽ chưa có hiệu lực.

### Cách khác: chỉ cài bằng plugin

Nếu bạn không muốn thêm file nào vào dự án, README có đường cài bằng plugin. Chạy các lệnh này bên trong Claude Code (không phải ngoài terminal):

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo
```

Các dòng này lần lượt: thêm kho plugin của Ruflo, cài lõi, cài bảng điều khiển, cài mod, nạp lại plugin, rồi mở `/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 ý sự khác biệt giữa hai đường. Đường plugin nhẹ hơn, không thêm file vào workspace và không cài hook. Đường `npx ruflo init` là bộ đầy đủ (agent, lệnh, skill, MCP server, hook, daemon). README khuyên dùng đường đầy đủ nếu bạn muốn mọi thứ hoạt động đúng như tài liệu.

### Dùng với Codex hoặc ứng dụng MCP khác

Với Codex hay ứng dụng MCP khác, bạn không cần cài vào dự án. Hãy cấu hình MCP server với **command** là `npx` và **arguments** như sau:

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

Hoặc chạy trực tiếp:

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

Vị trí điền cấu hình MCP phụ thuộc vào từng ứng dụng, README chưa hướng dẫn chi tiết cho từng ứng dụng. Bạn hãy xem phần MCP trong tài liệu của chính ứng dụng đó.

### Chỉ muốn xem bảng điều khiển ở terminal

Bảng điều khiể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 duy nhất, tiện cho script.

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

Theo README, cách kiểm tra đơn giản nhất như sau:

1. Chạy `npx ruflo@latest init` không báo lỗi trong thư mục dự án.
2. Mở lại Claude Code ở cùng thư mục, rồi gõ `/ruflo`. Bảng điều khiển phải hiện ra.
3. Với đường plugin, gõ `/plugin` để mở danh sách và xác nhận các mod như `ruflo-console`, `ruflo-mods` có trong dòng mod đang hoạt động.
4. Thử nhanh bằng `npx ruflo tui` ở terminal. Nếu thấy giao diện hiện lên là Ruflo đã chạy được.

Bạn cũng nên xem trong thư mục dự án có xuất hiện `.claude/` và `.claude-flow/` hay chưa. Đó là dấu hiệu `init` đã ghi file.

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

Tư liệu không đưa ra kết quả cụ thể của từng việc, nên dưới đây mình chỉ mô tả cách làm bám theo những gì README nêu.

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

**Bối cảnh:** bạn là dev mới vào một dự án cũ, ít test, chưa biết module nào dễ hỏng.

**Cách làm:** sau khi `init` và mở lại Claude Code, dán đúng câu README gợi ý:

```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:** swarm tìm module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Bạn vẫn nên đọc lại diff trước khi giữ.

> Model viết code, harness mới là thứ giúp nó làm việc cả buổi mà không quên.
>
> — Ông T

### Tạo một "mission" và giữ quyền kiểm soát

**Bối cảnh:** bạn muốn thử để Claude tự thao tác trên bảng điều khiển nhưng sợ nó làm quá tay.

**Cách làm:** cài console, mở `/ruflo`, vào **Settings → Claude control**, chọn **write + ask**. Rồi nhờ:

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

Claude sẽ mở mục Missions và đặt mục tiêu. Bạn xác nhận hành động tạo khi được hỏi. Sau đó kiểm tra mục Missions và Overview có ghi lại hành động chưa.

**Kết quả:** có một mission mới trong danh sách. README nhấn mạnh việc tạo mission không có nghĩa tính năng đã được làm xong. Muốn dừng, bấm **Take back control**. Mặc định hiện tại là **read + ask**, các hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần bạn xác nhận.

### Theo dõi chi phí token khi chạy agent

**Bối cảnh:** bạn dùng Claude Code hằng ngày và muốn biết agent tiêu bao nhiêu token.

**Cách làm:** mở bảng điều khiển bằng `/ruflo` để xem token và chi phí cạnh Claude Code. Nếu cần ngân sách và cảnh báo, README có plugin riêng:

```text
/plugin install ruflo-cost-tracker@ruflo
```

**Kết quả:** bạn thấy mức dùng và nhận cảnh báo chi phí theo mô tả của plugin. Mình chưa có thông tin chi tiết về định dạng báo cáo.

### Chỉ thử một plugin lẻ, không đụng dự án

**Bối cảnh:** bạn chỉ muốn thử riêng tính năng tạo test mà chưa muốn cài cả bộ.

**Cách làm:** thêm kho plugin rồi cài đúng plugin cần:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-testgen@ruflo
```

**Kết quả:** bạn có thêm lệnh và agent của plugin đó mà không có file nào được thêm vào workspace. Cách tiếp cận này an toàn để làm quen trước khi quyết định cài đầy đủ.

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

**Claude Code không thấy gì mới sau `init`.** Nguyên nhân thường là Claude Code đang mở từ trước. README nói nó nhận cấu hình ở lần khởi động tiếp theo. Hãy đóng và mở lại ở đúng thư mục dự án. Với plugin, thử `/reload-plugins`.

**Lệnh `npx` báo lỗi hoặc không chạy.** Hãy kiểm tra phiên bản Node bằng `node --version`. `package.json` yêu cầu từ 20.0.0 trở lên. Nếu thấp hơn, hãy nâng cấp Node rồi chạy lại.

**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` ngoài terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code. Cũng nhớ gõ các lệnh `/plugin` bên trong Claude Code, không phải trong PowerShell.

**Cài hai lần ra trùng lệnh.** Với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`, README cảnh báo nên cài từ một kho duy nhất, nếu không mod và lệnh sẽ nạp hai lần. Hãy gỡ bản thừa.

**Tên công cụ MCP không giống tài liệu.** Plugin `ruflo-core` đăng ký công cụ dưới dạng `mcp__plugin_ruflo-core_ruflo__*`, khác với tên ngắn của đường CLI. Nếu làm theo tài liệu dùng tên ngắn mà không chạy, hãy kiểm tra bạn đang dùng đường cài nào.

**`CLAUDE.md` bị thay đổi.** Đường `init` ghi file vào dự án. Hãy dùng git hoặc sao lưu trước khi chạy để có thể quay lại. Nếu muốn xem trước với cờ Grok, README có `--dry-run`.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có bảng điều khiển để nhìn thấy agent đang làm gì. Có phân quyền rõ (read, write, manage, full; ask hoặc auto) và nút lấy lại quyền kiểm soát. Hỗ trợ cả Claude Code lẫn Codex và các ứng dụng MCP. Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Hệ thống rất lớn: README nhắc tới hàng trăm công cụ MCP và hàng chục lệnh CLI, nên người mới dễ choáng. Phần bộ nhớ và học vẫn cần embedding và module cấu hình, không phải bật là xong. README cũng thừa nhận một số đ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. Mod chạy với quyền tài khoản, không có sandbox. Mình chưa có thông tin về chi phí token thực tế khi chạy swarm lớn.

**Khi nào 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 nhỏ, Ruflo là thừa. Nếu máy chứa dữ liệu nhạy cảm và bạn chưa muốn thêm hook hay mod chạy bằng quyền của mình, hãy thử đường plugin lẻ trước. Nếu đã có quy trình agent riêng, hãy xem Ruflo như tham khảo thay vì thay thế.

Lời khuyên của mình: thử trên một dự án nhỏ hoặc bản sao, dùng git để dễ quay lại, bắt đầu với quyền **read + ask**, rồi mới nâng 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 thân mã nguồn miễn phí sử dụng. Tuy nhiên Ruflo điều phối các model như Claude hay Codex, và chi phí của các dịch vụ đó tính riêng. Tư liệu chưa nêu cụ thể mức phí.

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

Tư liệu README chưa nêu yêu cầu GPU cho phần cài cơ bản. Một plugin tên ruflo-ruvector có nhắc tới tìm kiếm tăng tốc bằng GPU, nhưng đó là tuỳ chọn. Yêu cầu duy nhất được nêu rõ là Node 20 trở lên.

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

Mở terminal trong thư mục dự án và chạy `npx ruflo@latest init`, rồi mở lại Claude Code ở cùng thư mục. Nếu không muốn thêm file vào dự án, bạn có thể cài bằng plugin trong Claude Code, cần bản 2.1.287 trở lên.

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

README phần tư liệu này chưa nêu rõ hệ điều hành được hỗ trợ. Các lệnh đều dựa trên Node và npx nên về nguyên tắc cần Node 20 trở lên. Bạn nên xem thêm thư mục docs trong repo để biết chi tiết cho Windows.

### Ruflo có dùng được với Codex hoặc công cụ ngoài Claude Code không?

Có. README nói Codex và các ứng dụng MCP khác dùng được: cấu hình command là `npx` và arguments là `["-y", "ruflo@latest", "mcp", "start"]`. Cách thiết lập cụ thể phụ thuộc vào từng ứng dụng.

### Dữ liệu và quyền truy cập có an toàn không?

Bảng điều khiển cho phép chọn mức quyền read, write, manage hoặc full, với chế độ ask hoặc auto. Mặc định hiện tại là read + ask, và các hành động liên quan mạng, chi tiêu hoặc phá hủy luôn cần xác nhận. Tuy nhiên mod chạy với quyền tài khoản của bạn và không nằm trong sandbox, nên cần đọc code trước khi cài.

### Ruflo khác gì Claude Flow?

Theo README, Claude Flow là tên cũ, nay đã đổi thành Ruflo. Tác giả là Reuven Cohen (rUv). Gói npm trong metadata vẫn có tên claude-flow, còn README hướng dẫn chạy lệnh `ruflo`.
