# ruflo: điều phối đội 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 agent harness mã nguồn mở giấy phép MIT, đặt quanh Claude Code và Codex để thêm agent, bộ nhớ, hook và máy chủ MCP. Bạn dùng nó để giao việc lớn cho nhiều agent phối hợp, có nhớ giữa các phiên. Cài chỉ một lệnh npx trong thư mục dự án, cần Node từ bản 20 trở lên.

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

Ruflo là một "agent harness": lớp công cụ đặt bên ngoài Claude Code hoặc Codex để AI không chỉ trả lời, mà còn có agent chuyên biệt, bộ nhớ, vòng lặp và các chốt kiểm soát. Nói đơn giản: mô hình AI là người viết, còn Ruflo là cái bàn làm việc đầy đủ đồ nghề xung quanh người đó. Repo trước đây tên 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 lại "quên sạch", hoặc muốn giao một việc lớn cho nhiều agent chia nhau làm, thì Ruflo dành cho bạn. Người mới cũng dùng được: tác giả nói rõ bạn không cần học hết hàng trăm công cụ, chỉ cần chạy lệnh khởi tạo rồi dùng Claude Code như bình thường.

Điểm đáng giá nhất là cách cài rất gọn: một lệnh `npx` trong thư mục dự án, khởi động lại Claude Code là có agent, hook, bộ nhớ và máy chủ MCP. Ngoài ra còn có bảng điều khiển (console) để bạn theo dõi agent, token và chi phí ngay cạnh Claude Code.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung (harness) bao quanh Claude Code và Codex, thêm agent chuyên biệt, bộ nhớ dài hạn, hook tự động và bảng điều khiển để AI làm việc theo nhóm.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Theo README, Ruflo thêm vào Claude Code và Codex các nhóm khả năng sau.

- **Nhiều agent chuyên biệt làm việc như một đội (swarm).** Thay vì một AI làm hết, các agent tự chia việc. Lợi ích thực tế: một yêu cầu như "rà soát repo, viết test, tóm tắt thay đổi" được tách thành nhiều phần nhỏ.
- **Bộ nhớ nhớ qua nhiều phiên.** Agent lưu lại những gì đã làm và đã học. Lần sau bạn không phải giải thích lại từ đầu.
- **Hook tự động.** Sau khi cài, hệ thống tự định tuyến tác vụ và học từ những mẫu làm việc thành công ở nền, bạn không phải gọi từng công cụ.
- **Máy chủ MCP.** Ruflo chạy như một máy chủ MCP nên Codex hoặc các ứng dụng hỗ trợ MCP khác cũng dùng được.
- **Bảng điều khiển (console).** Xem workflow, agent, mô hình, token và chi phí; mở log và kết quả của từng lần chạy, tìm kiếm, phát lại và so sánh. Bạn còn đổi được giao diện bằng Theme Studio.
- **Cho Claude điều khiển console, nhưng bạn đặt giới hạn.** Có bốn mức quyền: `read`, `write`, `manage`, `full`, và hai kiểu duyệt: `ask` hoặc `auto`. Mặc định hiện 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, kể cả khi để `auto`.
- **Hệ plugin.** README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học tập, kiểm thử, bảo mật, DevOps, tiện ích mở rộng… 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 giữa nhiều máy (federation).** Agent trên các máy khác nhau phối hợp được với nhau mà README nói là không làm lộ dữ liệu. Phần này nâng cao, người mới chưa cần.

```note
Một lưu ý trung thực từ chính README: các video minh họa dùng dữ liệu mẫu hoặc phát lại khung hình, chúng không chứng minh swarm đã hoàn thành việc thật. Hãy tự thử trên một dự án nhỏ trước khi tin vào bất cứ điều gì.
```

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

Tư liệu của repo nói những điều sau, mình không thêm gì ngoài đó:

- **Node.js từ bản 20.0.0 trở lên** (theo `package.json`). Cách cài chính dùng `npx`, đi kèm Node.
- **Claude Code** nếu bạn muốn dùng đường cài đầy đủ. Đường cài chỉ bằng plugin cần Claude Code **2.1.287 trở lên**; lệnh cài plugin từ terminal cầ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. Chỉ cần trỏ nó tới lệnh khởi động máy chủ MCP của Ruflo.
- **Một thư mục dự án** để chạy lệnh khởi tạo.

Tư liệu không nói rõ về hệ điều hành, dung lượng ổ đĩa hay phần cứng (GPU). Gói npm của repo có tên `claude-flow`, nhưng README hướng dẫn gọi bằng tên `ruflo`. Phần giá cả dịch vụ AI (tài khoản Claude, Codex) cũng chưa được nói trong README; bạn cần có quyền dùng công cụ AI đó theo cách riêng của mình.

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

```steps
- Mở terminal trong thư mục dự án | Đứng đúng thư mục bạn muốn thêm Ruflo vào
- Chạy lệnh init | npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nạp cấu hình mới
- Giao một việc thật | Gõ yêu cầu dùng swarm của Ruflo
- (Tuỳ chọn) Cài console | Dùng plugin để có bảng điều khiển /ruflo
```

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

Lỗi người mới hay gặp nhất là chạy lệnh ở sai chỗ. Hãy `cd` vào thư mục dự án của bạn trước. Lệnh `init` sẽ ghi file vào thư mục hiện tại.

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

Thay `ten-thu-muc-du-an-cua-ban` bằng đường dẫn thật của bạn.

### Chạy lệnh khởi tạo

Đây là lệnh chính theo README. Nó thêm agent, hook, bộ nhớ và máy chủ MCP của Ruflo vào dự án.

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

Bảng so sánh trong README cho biết đường này tạo ra các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file helper và settings trong dự án. Vì vậy nên chạy trong một dự án có quản lý phiên bản (git) để dễ xem lại những gì bị thêm vào. Nếu muốn cấu hình theo từng câu hỏi, README có thêm chế độ hướng dẫn:

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

### Mở Claude Code và giao việc

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nạp các thành phần mới ở lần khởi động kế tiếp, nên nếu nó đang mở sẵn thì hãy tắt rồi mở lại. Sau đó thử một yêu cầu thật, ví dụ lấy từ 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 câu này bằng tiếng Việt, nhưng mình khuyên cứ giữ nguyên cụm "ruflo swarm" để Claude hiểu bạn muốn dùng đội agent.

### Cách khác: chỉ cài plugin cho Claude Code

Nếu bạn không muốn thêm file nào vào dự án, README có đường cài chỉ bằng plugin (cần Claude Code 2.1.287 trở lên). Các lệnh này gõ **bên trong 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
```

Dòng `/ruflo` ở cuối mở bảng điều khiển. 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
```

So sánh nhanh theo README: đường plugin không thêm file nào vào workspace và không cài hook, chỉ có lệnh gạch chéo và vài skill; đường `npx ruflo init` mới có đủ vòng lặp (98 agent, hơn 60 lệnh, 30 skill, máy chủ MCP, hook, daemon) nên hợp để dùng thật.

```note
Các "mod" chạy với quyền tài khoản của bạn và không bị đóng hộp cách ly. README khuyên bạn đọc code của mod trước khi cài. Hãy nghiêm túc làm bước này.
```

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

Không cần cài vào dự án. Trong phần cấu hình máy chủ MCP của ứng dụng, đặt lệnh (command) là `npx` và các đối số (arguments) là `["-y", "ruflo@latest", "mcp", "start"]`. Tức là tương đương chạy lệnh:

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

Mỗi ứng dụng có chỗ điền cấu hình khác nhau; README của Ruflo không hướng dẫn chi tiết từng ứng dụng, bạn xem tài liệu của ứng dụng đó.

### Chạy bảng điều khiển trong terminal thường

Console cũng chạy độc lập, không cần Claude Code:

```bash
npx ruflo tui
```

Thêm `--plain` để in ra đúng một khung hình, tiện cho script.

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

README không đưa ra một lệnh "kiểm tra cài đặt" riêng, nên mình chỉ nêu các dấu hiệu có trong tư liệu:

- Sau `npx ruflo@latest init`, thư mục dự án có thêm `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Mở lại Claude Code rồi gõ `/ruflo`: bảng điều khiển hiện ra. Với cách cài plugin, bạn cũng có thể mở `/plugin` để xem các mod đang hoạt động trong dòng "active mods".
- Trong console, `/ruflo market` mở danh mục plugin (Plugin Catalog), nơi có nút cài, bật, tắt và cập nhật; mỗi thao tác đều hỏi lại bạn.
- Chạy thử `npx ruflo tui --plain`: nếu in ra một khung hình thì phần giao diện đã chạy.

Nếu lệnh `/ruflo` không xuất hiện, đừng vội cho là hỏng: thử khởi động lại Claude Code hoặc gõ `/reload-plugins`.

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

### Dev mới nhận một repo lạ cần rà soát

Bối cảnh: bạn vừa vào công ty, được giao một repo cũ không có tài liệu. Chạy `npx ruflo@latest init` trong thư mục repo, mở lại Claude Code, rồi dán yêu 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: Claude chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt thay đổi. Hãy đọc kỹ phần test và diff trước khi gộp vào nhánh chính.

### Người làm sản phẩm muốn thử giao việc nhưng kiểm soát chặt

Bối cảnh: bạn không phải dev, chỉ muốn xem agent làm gì mà không để nó tự ý hành động. Cài console qua plugin, mở `/ruflo`, vào Settings, chọn Claude control, rồi đặt mức write + ask. Sau đó yêu cầu:

```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. Kết quả: Missions có mục tiêu mới 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. Muốn dừng, bấm **Take back control**.

> Agent giỏi đến đâu cũng cần một người đặt ranh giới: chọn `ask` trước, nới quyền sau.
>
> — Ông T

### Người dùng Codex hoặc công cụ khác muốn có bộ nhớ cho agent

Bối cảnh: bạn không dùng Claude Code mà dùng Codex. Thay vì cài vào dự án, bạn trỏ ứng dụng tới `npx -y ruflo@latest mcp start`. Kết quả: các công cụ của Ruflo (như bộ nhớ và điều phối) xuất hiện trong ứng dụng qua giao thức MCP. Mức độ hoạt động cụ thể tuỳ từng ứng dụng, README không cam kết chi tiết.

### Nhóm nhỏ muốn theo dõi chi phí và test

Bối cảnh: một nhóm nhỏ dùng Claude Code hằng ngày và lo tiền token. Cài thêm plugin theo danh mục (ví dụ `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo; `ruflo-testgen` để tìm test còn thiếu). Lệnh cài đúng mẫu `/plugin install tên-plugin@ruflo`. Kết quả mong đợi theo mô tả plugin: có số liệu chi phí và danh sách chỗ thiếu test. Bạn nên cài từng plugin một và đọc mô tả trước khi bật.

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

**Chạy `init` rồi mà Claude Code không có gì mới.** Nguyên nhân thường là Claude Code đang mở từ trước. README nói nó nạp thành phần mới ở lần khởi động kế tiếp. Tắt hẳn rồi mở lại trong đúng thư mục dự án.

**Lệnh `/plugin ...` báo lỗi hoặc không nhận.** Có thể phiên bản Claude Code quá cũ: đường plugin cần 2.1.287 trở lên, lệnh cài từ terminal cần 2.1.292 trở lên. Cập nhật Claude Code, rồi chạy `/reload-plugins`. Nhớ rằng các lệnh bắt đầu bằng dấu `/` gõ trong Claude Code, không gõ trong terminal.

**`npx` báo lỗi hoặc không chạy.** `package.json` yêu cầu Node từ bản 20 trở lên. Kiểm tra bản Node đang dùng bằng `node --version` và nâng cấp nếu thấp hơn. Lệnh này là lệnh phổ thông, an toàn.

**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`, `agentic-flow`: chỉ cài từ một marketplace, nếu bật từ cả hai thì mod và lệnh bị nạp hai lần. Hãy gỡ một bên.

**Cho Claude quá nhiều quyền.** Nếu nâng lên `full` và `auto` mà chưa hiểu rõ, agent có thể làm nhiều thứ ngoài ý muốn. Hãy quay về read + ask, và dùng **Take back control** khi thấy lạ. Ngoài ra, đừng quên thư mục `.claude/`, `.claude-flow/` và `CLAUDE.md` do `init` thêm vào; nếu bạn không muốn đưa chúng vào kho chung, hãy kiểm tra trước khi commit.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có sẵn rất nhiều agent, plugin và bộ nhớ nên bạn không phải tự lắp. Có bảng điều khiển để nhìn thấy agent đang làm gì, và có cơ chế quyền rõ ràng (read/write/manage/full, ask/auto). Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây. Dùng được cả với Claude Code, Codex và các ứng dụng MCP khác.

**Giới hạn.** Hệ thống rất lớn: README nhắc tới hơn 400 công cụ MCP và hơn 60 lệnh CLI, nên người mới dễ choáng. Một số mô tả, như vòng học tự động, được README tự gọi là "khái niệm", và các video minh họa dùng dữ liệu mẫu. Đường cài đầy đủ ghi nhiều file vào dự án. Các mod không bị cách ly. Tư liệu cũng chưa nói về hệ điều hành được hỗ trợ hay chi phí khi chạy nhiều agent cùng lúc, bạn nên tự theo dõi.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần một AI trả lời câu hỏi lẻ, hoặc việc nhỏ trong một file, dùng Claude Code hoặc Codex thuần là đủ, không cần thêm một lớp harness. Nếu bạn chỉ muốn thử một tính năng, hãy bắt đầu bằng đường plugin (không thêm file vào dự án) rồi mới cân nhắc `init` đầy đủ.

Lời khuyên của mình: thử trên một dự án nhỏ hoặc nhánh riêng, giữ quyền ở mức read + ask, rồi mới nới dần khi bạn đã quen.

## Câu hỏi thường gặp

### Ruflo có miễn phí không?

Repo dùng giấy phép MIT, tức mã nguồn mở. Tư liệu không nói gì về chi phí của dịch vụ AI chạy phía sau (như Claude hay Codex), nên phần đó bạn cần tự kiểm tra theo tài khoản của mình. Có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

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

Đây là cùng một dự án. README cho biết Claude Flow đã được đổi tên thành Ruflo, và gói npm của repo vẫn có tên claude-flow. Cách gọi trong hướng dẫn hiện nay là npx ruflo.

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

Cần Node.js từ bản 20.0.0 trở lên. Nếu dùng đường cài plugin thì cần Claude Code 2.1.287 trở lên. Dùng với Codex hoặc ứng dụng MCP khác thì chỉ cần cấu hình lệnh npx -y ruflo@latest mcp start.

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

Có nếu bạn dùng npx ruflo init: README nói nó thêm .claude/, .claude-flow/, CLAUDE.md, file helper và settings vào workspace. Nếu muốn không thêm file nào, dùng đường cài chỉ bằng plugin. README cũng có lệnh init --grok kèm cờ --dry-run để xem trước.

### Claude có tự ý làm bậy trong bảng điều khiển không?

README mô tả cơ chế quyền: bạn chọn mức read, write, manage hoặc full, và ask hoặc auto. Mặc định hiện là read + ask. Các hành động mạng, chi tiêu và phá hủy vẫn cần xác nhận kể cả khi để auto, và bạn có thể bấm Take back control để dừng.

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

Tư liệu mình có chưa nói rõ về hệ điều hành hay yêu cầu GPU. Điều chắc chắn là cần Node từ bản 20 trở lên. Bạn nên xem README và tài liệu trong repo hoặc tự thử trên một dự án nhỏ.

### Dữ liệu của tôi có an toàn không?

README nói phần federation giúp agent trên nhiều máy trao đổi mà không làm lộ dữ liệu, và có plugin như ruflo-aidefence để chặn prompt injection và phát hiện thông tin cá nhân. Tuy vậy, các mod chạy với quyền tài khoản của bạn và không bị cách ly, nên hãy đọc code trước khi cài.
