# 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à bộ công cụ bọc quanh Claude Code và Codex, giúp nhiều AI agent phối hợp thành đội, có bộ nhớ giữa các phiên và có hooks tự định tuyến công việc. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Với người đã dùng Claude Code thì cài khá dễ, nhưng bộ tính năng rất rộng nên nên bắt đầu từ một tác vụ nhỏ.

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

Ruflo là một “agent meta-harness”: lớp công cụ bọc quanh Claude Code và Codex để AI không chỉ trả lời từng câu mà còn làm việc theo đội. Hiểu đơn giản: mô hình AI là người viết, còn harness là bàn làm việc đầy đủ dụng cụ quanh người đó. Ruflo thêm vào bàn làm việc ấy các agent chuyên biệt, bộ nhớ, vòng lặp và các lớp kiểm soát.

Bạn nên xem repo này nếu đang dùng Claude Code (hoặc Codex) và thấy một agent đơn lẻ chưa đủ. Ví dụ bạn muốn một nhóm agent cùng rà soát dự án, viết test, rồi tóm tắt lại những gì đã đổi. Người mới cũng dùng được, vì tác giả nói rõ bạn không cần học hết hàng trăm công cụ. Sau khi chạy `init`, bạn cứ dùng Claude Code như bình thường, còn hooks sẽ tự định tuyến tác vụ và học từ các lần làm thành công.

Điểm đáng giá nhất là cách cài rất gọn: một lệnh `npx` là xong phần nền. Repo hiện có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, ngôn ngữ chính là TypeScript và vẫn được cập nhật trong vài tháng gần đây.

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

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

Theo README, Ruflo là phần “thực thi” xung quanh Claude Code và Codex. Dưới đây là những nhóm tính năng đáng quan tâm nhất, nói theo lợi ích thực tế.

### Đội agent làm việc cùng nhau

Ruflo đi kèm hàng trăm agent chuyên biệt (README nhắc “100+”, bảng so sánh ghi 98 agent). Chúng được tổ chức thành “swarm”, tức một nhóm agent chia việc cho nhau. Thay vì bạn tự giao từng việc nhỏ, bạn mô tả mục tiêu lớn và để nhóm tự phân công.

### Bộ nhớ qua nhiều phiên

Agent có bộ nhớ, nên kinh nghiệm từ lần làm trước được dùng lại cho lần sau. README còn nói bộ nhớ này phản hồi ngược vào bước định tuyến tác vụ. Có các plugin riêng cho việc này, ví dụ lưu và khôi phục bộ nhớ giữa các phiên, hay tìm kiếm thông minh kết hợp nhiều kiểu tìm.

Lưu ý trung thực: README ghi rằng vòng học này là mô hình khái niệm. Phần truy xuất vector cục bộ có thể chạy không cần LLM, nhưng vẫn cần embeddings và các module học đã được cấu hình.

### Hooks tự định tuyến

Sau `init`, hệ thống hooks chạy nền: định tuyến tác vụ, học từ mẫu làm tốt và điều phối agent. Với người mới, đây là phần “đỡ phải nghĩ” nhất.

### Bảng điều khiển ngay cạnh Claude Code

Plugin `ruflo-console` là một “cockpit”: theo dõi workflow, agent, mô hình, token và chi phí. Bạn có thể mở log và kết quả của 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. Gõ `/ruflo` trong Claude Code để mở.

### Để Claude lái, bạn đặt giới hạn

Bạn có thể cho Claude điều khiển bảng điều khiển ở một trong bốn mức: `read`, `write`, `manage` hoặc `full`, kèm chế độ phê duyệt `ask` hoặc `auto`. Mặc định hiện tại là read + ask. Hành động vượt quyền sẽ bị từ chối. Các hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận kể cả khi để `auto`.

### Hệ sinh thái plugin lớn

README liệt kê 48 plugin, chia nhóm: điều phối, bộ nhớ, học và trí tuệ, kiểm thử chất lượng, bảo mật, kiến trúc, DevOps và các nhóm khác. Một vài ví dụ: `ruflo-testgen` tìm test còn thiếu và tạo ra, `ruflo-security-audit` quét lỗ hổng, `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)

Theo README, agent trên các máy khác nhau có thể trao đổi với nhau một cách an toàn mà không làm lộ dữ liệu. Tính năng này dành cho nhu cầu nâng cao, người mới có thể bỏ qua lúc đầu.

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

- **Node.js từ 20.0.0 trở lên.** File `package.json` của repo yêu cầu như vậy. README chưa hướng dẫn cách cài Node, bạn lấy bản cài từ trang chủ Node.js.
- **Claude Code** nếu bạn dùng đường cài chính. Tác vụ mẫu trong README là mở Claude Code trong cùng thư mục dự án.
- **Claude Code bản 2.1.287 trở lên** nếu bạn chọn đường cài chỉ bằng plugin. Lệnh cài từ terminal cần bản 2.1.292 trở lên.
- **Một thư mục dự án** để chạy lệnh cài. README nói rõ: chạy trong thư mục dự án của bạn.
- **Codex hoặc client MCP khác** cũng dùng được, nếu client cho phép khai báo lệnh MCP server.

Về tài khoản, API key và phần cứng: README (phần mình có) chưa nêu yêu cầu cụ thể. Hệ điều hành cũng chưa được nói rõ. Chi phí gọi mô hình tuỳ vào công cụ AI bạn đang dùng, không phải thứ Ruflo ghi sẵn.

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

README đưa ra nhiều đường cài. Mình hướng dẫn đường chính trước, rồi hai đường phụ.

```steps
- Kiểm tra Node | Bảo đảm máy có Node.js từ bản 20 trở lên
- Mở terminal đúng chỗ | Vào thư mục dự án mà bạn muốn gắn Ruflo
- Chạy init | Gõ một lệnh npx để thêm agent, hooks, bộ nhớ và MCP server
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Gõ /ruflo | Mở bảng điều khiển để xác nhận đã chạy
```

### Kiểm tra Node

Trước tiên hãy chắc máy có Node bản 20 trở lên. Bạn có thể mở terminal và gõ lệnh dưới đây để xem phiên bản. Lệnh này là lệnh phổ thông của Node, không nằm trong README của Ruflo.

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 20, hãy cập nhật Node rồi mới tiếp tục.

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

Đây là chỗ người mới hay vấp nhất. `init` ghi file vào thư mục hiện tại, nên bạn phải đứng đúng trong dự án của mình. Ví dụ:

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

Hãy thay `duong-dan-toi-du-an-cua-ban` bằng đường dẫn thật. Nếu bạn dùng Windows, bạn có thể mở thư mục dự án rồi mở terminal từ chính thư mục đó.

### Chạy lệnh init

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

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

`npx` tải Ruflo bản mới nhất rồi chạy lệnh `init`. Theo README, lệnh này thêm agent, hooks, bộ nhớ và MCP server của Ruflo vào dự án. Bảng so sánh trong README cho biết đường này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file helper và settings. Vì vậy hãy chạy trong dự án bạn đã commit hoặc sao lưu, để dễ xem Ruflo đã thêm gì.

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

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

### Mở lại Claude Code

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent, hooks, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn Claude Code, hãy thoát rồi mở lại.

### Đường cài khác: chỉ dùng plugin của Claude Code

Đường này không thêm file nào vào dự án và cần Claude Code từ 2.1.287 trở lên. Bạn gõ các lệnh sau **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
```

Lệnh đầu thêm “chợ” plugin của Ruflo. Ba lệnh `install` cài lõi, bảng điều khiển và các mod. `/reload-plugins` nạp lại để dùng ngay. Từ terminal, với Claude Code 2.1.292 trở lên, README ghi một lệnh tương đương:

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

Cần biết thêm: đường chỉ-plugin nhẹ hơn nhưng ít tính năng hơn. README so sánh rằng đường `npx ruflo init` mới có “vòng Ruflo” đầy đủ (agent, lệnh, skill, MCP server, hooks, daemon) và khuyên dùng cho công việc thật.

### Đường cài khác: Codex hoặc client MCP khác

Bạn không cần thiết lập dự án. Chỉ cần khai báo trong client:

- **command:** `npx`
- **arguments:** `["-y", "ruflo@latest", "mcp", "start"]`

Dạng JSON dưới đây chỉ minh hoạ hai giá trị trên. Mỗi client có định dạng file cấu hình khác nhau, nên bạn hãy xem tài liệu của client đó để biết đặt vào đâu.

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

```note
Mod của Ruflo chạy với quyền của tài khoản bạn và không có sandbox. README khuyên bạn đọc code của mod trước khi cài. Tương tự, hãy để mức điều khiển của Claude ở read + ask khi mới làm quen, và chỉ nâng lên khi bạn hiểu rõ mình đang cho phép điều gì.
```

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

README không đưa ra một đoạn “output mẫu” cố định, nhưng đưa ra các dấu hiệu rõ ràng:

- Sau `npx ruflo@latest init`, thư mục dự án có thêm các mục như `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Khởi động lại Claude Code rồi gõ `/ruflo`. Nếu bảng điều khiển mở ra, bạn đã cài thành công.
- Nếu cài bằng plugin, gõ `/plugin` để xem. README nói các plugin sẽ hiện trong dòng “active mods”.
- Muốn thử ngoài Claude Code, chạy giao diện terminal độc lập:

```bash
npx ruflo tui
```

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

```bash
npx ruflo tui --plain
```

Cuối cùng, thử một tác vụ thật như phần dưới để chắc rằng agent hoạt động.

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

Các tình huống dưới đây bám theo ví dụ README mô tả. Mình không hứa kết quả cụ thể vì nó tuỳ vào dự án của bạn.

### Rà soát một dự án đang chạy

Bối cảnh: bạn là lập trình viên nhận lại một repo cũ, chưa ai dám đụng. Bạn chạy `npx ruflo@latest init` trong thư mục repo, mở lại Claude Code, rồi dán 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.
```

Câu này yêu cầu 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 là một bản tóm tắt thay đổi để tự đọc lại. Hãy xem lại phần test do agent viết trước khi giữ.

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

### Giao việc có kiểm soát qua bảng điều khiển

Bối cảnh: bạn là quản lý sản phẩm, muốn thử để Claude tạo “mission” nhưng chưa muốn nó tự làm bừa. Làm theo các bước README gợi ý:

1. Cài `ruflo-console`, mở `/ruflo`, vào Settings → Claude control và chọn **write + ask**.
2. Gõ yêu cầu cụ thể: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
3. Khi Claude mở mục Missions và đặt mục tiêu, bạn xác nhận hành động tạo đang chờ.
4. Kiểm tra mục Missions và Overview có ghi lại hành động.

Kết quả: một mission được tạo, nằm trong danh sách để bạn theo dõi. README nhấn mạnh rằng tạo mission không có nghĩa tính năng đã được làm. Nếu cần dừng, bấm **Take back control**, các lời gọi sau của Claude sẽ bị từ chối cho tới khi bạn trả quyền.

### Dùng Ruflo từ Codex hoặc công cụ MCP khác

Bối cảnh: nhóm bạn dùng Codex chứ không phải Claude Code. Bạn không cần gắn gì vào dự án, chỉ khai báo MCP server với lệnh `npx` và các tham số `-y`, `ruflo@latest`, `mcp`, `start` như phần cài đặt ở trên. Sau đó client có thể gọi công cụ của Ruflo. Mình chưa có tư liệu về danh sách công cụ cụ thể sẽ hiện ra ở từng client, nên bạn hãy kiểm tra trong chính client.

### Theo dõi chi phí và tiến độ bằng cửa sổ terminal

Bối cảnh: bạn muốn xem tiến độ agent mà không mở Claude Code. Chạy `npx ruflo tui` để xem bảng điều khiển ngay trong terminal. Nếu cần đưa vào script, dùng `--plain` để in một khung hình duy nhất. Muốn theo dõi token và đặt ngân sách, README có plugin `ruflo-cost-tracker` với mô tả “track token usage, set budgets, get cost alerts”.

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

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

Nguyên nhân hay gặp là chưa khởi động lại. README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy thoát hẳn rồi mở lại trong **đúng thư mục** bạn đã chạy `init`. Nếu dùng plugin, chạy `/reload-plugins`.

### Lệnh npx báo lỗi hoặc không chạy

Thường do Node chưa cài hoặc quá cũ. Repo yêu cầu Node 20 trở lên. Chạy `node --version` để kiểm tra rồi cập nhật nếu cần. Lệnh `npx` đi cùng Node nên không cần cài riêng.

### Lệnh plugin bị từ chối vì Claude Code quá cũ

Đường cài plugin cần Claude Code 2.1.287 trở lên, còn lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước khi thử lại.

### Plugin tải hai lần hoặc lệnh bị trùng

README cảnh báo với các plugin bên 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, mod và lệnh sẽ tải hai lần. Hãy gỡ một bản và giữ lại một.

### Claude từ chối thao tác trong bảng điều khiển

Đây thường không phải lỗi. Mức quyền mặc định là read + ask, nên hành động ghi hoặc quản lý bị từ chối. Vào Settings → Claude control để nâng mức theo ý bạn, và nhớ rằng thao tác liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả khi để `auto`.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Dùng MIT nên rộng rãi cho cá nhân và doanh nghiệp. Hỗ trợ cả Claude Code lẫn Codex qua MCP. Có bảng điều khiển với cơ chế giới hạn quyền rõ ràng. Hệ sinh thái plugin phong phú và repo vẫn được cập nhật.

**Giới hạn.** Bộ tính năng rất rộng (README nhắc hàng trăm công cụ MCP và hàng chục lệnh CLI), nên người mới dễ bị ngợp. Đườ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 và không có sandbox. Một số phần, như vòng học, README tự nhận là mô hình khái niệm. Các đoạn demo trong README dùng dữ liệu mẫu, chưa chứng minh được việc hoàn thành swarm thật hay khả năng nhớ lại.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần Claude Code trả lời vài việc đơn giản, bạn chưa cần Ruflo. Nếu muốn thử nhẹ, hãy dùng đường chỉ-plugin để không thêm file vào dự án. Nếu bạn cần chắc chắn về an toàn dữ liệu và chi phí, hãy bắt đầu trong một repo thử nghiệm, giữ mức quyền read + ask và đọc kỹ tài liệu bảo mật của repo trước khi dùng cho dự án quan trọng.

## 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 được dùng và sửa mã. Tư liệu mình có chưa nói gì về chi phí gọi mô hình AI, phần này tính theo công cụ bạn dùng như Claude Code hay Codex. README có plugin theo dõi token và đặt ngân sách nếu bạn muốn kiểm soát.

### Ruflo cài như thế nào, có khó không?

Đường chính chỉ cần một lệnh `npx ruflo@latest init` trong thư mục dự án, rồi mở lại Claude Code. Bạn cần Node từ bản 20 trở lên. Ngoài ra còn đường chỉ-plugin và đường cấu hình MCP cho Codex.

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

Tư liệu mình có chưa nói rõ về hệ điều hành được hỗ trợ. Điều README yêu cầu là Node 20 trở lên và Claude Code. Bạn nên tự thử trên một dự án thử trước khi dùng thật.

### Có cần GPU hoặc cấu hình máy mạnh không?

README ở phần mình có không nêu yêu cầu GPU cho đường cài chính. Một plugin riêng là ruflo-ruvector có nhắc tìm kiếm tăng tốc bằng GPU, nhưng đó là phần tuỳ chọn. Yêu cầu phần cứng cụ thể thì chưa có thông tin.

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

Bảng điều khiển có mức quyền read, write, manage, full và chế độ ask hoặc auto, mặc định là read + ask. Hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn cần xác nhận kể cả khi để auto. Tuy nhiên mod chạy với quyền tài khoản của bạn và không có sandbox, nên bạn nên đọc code trước khi cài.

### Ruflo khác gì dùng Claude Code thông thường?

Claude Code là công cụ để mô hình làm việc, còn Ruflo là lớp bao quanh thêm agent chuyên biệt, swarm, bộ nhớ, hooks và bảng điều khiển. Sau khi chạy init bạn vẫn dùng Claude Code như thường, còn hooks tự định tuyến và học trong nền.

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

Được theo README. Bạn khai báo command là `npx` với tham số `-y`, `ruflo@latest`, `mcp`, `start` trong client hỗ trợ MCP. README cũng có lệnh `npx ruflo init --grok` cho Grok Build, nhưng mình chưa có chi tiết cách dùng nên bạn xem hướng dẫn trong repo.
