# 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 agent harness, tức lớp công cụ bao quanh Claude Code và Codex, giúp nhiều agent AI chia việc, nhớ lại và phối hợp với nhau. Cài chỉ cần chạy `npx ruflo@latest init` trong thư mục dự án, yêu cầu Node từ 20 trở lên. Bạn cũng có thể chỉ cài dạng plugin cho Claude Code mà không thêm tệp nào vào dự án.

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

ruflo là một "agent harness": lớp công cụ đặt quanh Claude Code và Codex để các agent AI có thêm công cụ, bộ nhớ, vòng lặp làm việc và các chốt kiểm soát. Repo này trước đây tên là Claude Flow, do Reuven Cohen (rUv) xây dựng. Hiện repo có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, viết chủ yếu bằng TypeScript.

Nói đơn giản: Claude Code hay Codex là "người thợ" biết viết code. ruflo là cái bàn làm việc đầy đủ đồ nghề quanh người thợ đó. Nó cho phép gọi cả một nhóm agent (README gọi là swarm) cùng xử lý một việc, nhớ lại kinh nghiệm giữa các phiên làm việc, và hiển thị tiến trình trong một bảng điều khiển ngay cạnh Claude Code.

Nếu bạn là lập trình viên mới hoặc người đã quen dùng Claude Code và muốn giao những việc lớn hơn (rà soát cả repo, viết test hàng loạt), ruflo đáng thử. Điểm đáng giá nhất là cách cài: một lệnh `npx`, rồi dùng Claude Code như bình thường. README nói sau khi `init`, hệ thống hook tự định tuyến tác vụ và phối hợp agent ở phía sau.

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

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

README giới thiệu khá nhiều thứ. Mình gom lại những ý đáng chú ý nhất cho người mới.

### Nhóm agent làm việc cùng nhau

Sau khi cài, ruflo thêm các agent chuyên biệt vào dự án (bản cài bằng CLI ghi là 98 agent, hơn 60 lệnh, 30 skill). Thay vì một AI làm tuần tự, bạn có thể nhờ cả nhóm chia việc. Lợi ích thực tế là những việc dài như "rà soát cả repo" được tách thành các phần nhỏ.

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

ruflo có bộ nhớ để agent nhớ lại giữa các phiên làm việc và học từ những tác vụ đã làm tốt. README có ghi rõ một lưu ý trung thực: 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.

### Bảng điều khiển ngay trong Claude Code

Plugin `ruflo-console` là "buồng lái" cạnh Claude Code. Bạn xem được workflow, agent, model, token và chi phí, mở log và kết quả của từng lần chạy, tìm kiếm, xem lại và so sánh. Mở bằng lệnh `/ruflo`.

### Để Claude điều khiển bảng điều khiển, nhưng bạn đặt giới hạn

Trong Settings có mục Claude control với bốn mức: `read`, `write`, `manage`, `full`, kèm chế độ duyệt `ask` hoặc `auto`. Mặc định hiện tại là read + ask. Những hành động vượt quyền sẽ bị từ chối. 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ả ở chế độ `auto`. Có nút Take back control để thu lại quyền.

### Kho plugin lớn

README liệt kê 48 plugin, chia theo nhóm: điều phối (swarm, autopilot, workflows, federation), bộ nhớ (agentdb, rag-memory), chất lượng code (testgen, browser, docs), bảo mật (security-audit, aidefence), theo dõi chi phí (cost-tracker)... Bạn chỉ cần cài cái mình cần.

### Dùng được với Codex và các MCP client khác

Ngoài Claude Code, Codex và client MCP khác dùng được bằng cách trỏ tới `npx -y ruflo@latest mcp start`. README còn nhắc tới Grok Build qua `npx ruflo init --grok`.

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

- Node.js phiên bản 20.0.0 trở lên (theo `package.json`).
- Claude Code, nếu bạn dùng theo cách mặc định. Với đườ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` từ terminal cần 2.1.292 trở lên.
- Một thư mục dự án để chạy `init`.
- Nếu dùng Codex hoặc client MCP khác: client đó phải cho cấu hình một MCP server dạng lệnh.

README phần đã cung cấp không nói gì về yêu cầu GPU, hệ điều hành cụ thể hay API key riêng cho ruflo. Những mục này mình chưa có thông tin, bạn xem thêm trong thư mục `docs/` của repo.

```note
Các mod của ruflo chạy với quyền tài khoản của bạn và không chạy trong sandbox. README khuyên đọc code trước khi cài. Hãy giữ Claude control ở mức read + ask cho đến khi bạn hiểu rõ nó làm gì.
```

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

Có hai đường cài khác nhau về "độ sâu". Đường CLI cho đầy đủ mọi thứ và thêm tệp vào dự án. Đường plugin nhẹ hơn, không thêm tệp nào vào dự án.

```steps
- Mở terminal đúng thư mục | vào thư mục dự án của bạn, kiểm tra Node 20+
- Chạy init | npx ruflo@latest init để thêm agent, hook, bộ nhớ, MCP server
- Khởi động lại Claude Code | mở Claude Code trong cùng thư mục để nó nhận cấu hình
- Mở bảng điều khiển | gõ /ruflo trong Claude Code
- Tuỳ chọn: cài bằng plugin | dùng /plugin marketplace add ruvnet/ruflo nếu không muốn thêm tệp vào dự án
```

### Đường chính: chạy init trong thư mục dự án

Mở terminal (PowerShell trên Windows, Terminal trên macOS) và `cd` vào thư mục dự án của bạn. Chỗ người mới hay vấp là chạy lệnh ở sai thư mục, nên các tệp sẽ nằm sai chỗ. Kiểm tra Node trước:

```bash
node --version
```

Rồi chạy lệnh cài đặt của ruflo:

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

Lệnh này thêm agent, hook, bộ nhớ và MCP server vào dự án. Theo bảng so sánh trong README, bạn sẽ thấy các thư mục và tệp như `.claude/`, `.claude-flow/`, `CLAUDE.md`. Nếu muốn thiết lập tương tác từng bước, README ghi:

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

Với Grok Build, README có lệnh `npx ruflo init --grok` và cho thêm `--dry-run` để xem trước mà chưa ghi gì.

### Khởi động lại Claude Code

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

### Đường thay thế: chỉ cài plugin cho Claude Code

Đường này không thêm tệp nào vào dự án, nhưng chỉ có phần lệnh slash, skill và định nghĩa agent. Gõ các lệnh sau ngay 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
```

Từ terminal, trên Claude Code 2.1.292 trở lên, README cho lệnh một dòng:

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

Nếu cần thêm plugin khác (ví dụ swarm hay rag-memory), README dùng cùng cú pháp:

```text
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo
```

### Đường cho Codex hoặc MCP client khác

Trong phần cấu hình MCP của client, đặt **command** là `npx` và **arguments** là:

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

Đây chỉ là phần giá trị cấu hình README nêu. Cách khai báo cụ thể tuỳ từng client, mình chưa có thông tin về từng loại.

### Chạy bảng điều khiển ngoài Claude Code

Nếu chỉ muốn xem giao diện terminal, README cho biết có thể chạy riêng:

```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 mô tả một dòng "thành công" cố định, nên mình chỉ nêu những dấu hiệu nó có nhắc:

- Sau khi `init` và mở lại Claude Code, bạn thấy thêm các thư mục như `.claude/` và `.claude-flow/` cùng tệp `CLAUDE.md` trong dự án.
- Gõ `/ruflo` trong Claude Code thì mở được bảng điều khiển.
- Với đường plugin, mở `/plugin` và kiểm tra `ruflo-console`, `ruflo-mods` có xuất hiện trong dòng active mods.
- Trong bảng điều khiển, `/ruflo market` mở Plugin Catalog để xem, bật, tắt và cập nhật plugin (mỗi hành động đều hỏi trước).

Nếu `/ruflo` không nhận ra, hãy thử `/reload-plugins` hoặc khởi động lại Claude Code.

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

README nhấn mạnh bạn không cần học hết 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à mấy tình huống bám sát những gì tư liệu mô tả.

### 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 nhận lại một dự án không có người bàn giao. Chạy `init`, mở Claude Code trong thư mục dự án và đưa đú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: một nhóm agent tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã đổi. Hãy đọc kỹ phần tóm tắt và chạy test bằng tay để xác nhận.

> Đừng học 406 công cụ. Cài xong, cứ giao việc thật cho Claude Code và để phần điều phối chạy ngầm.
>
> — Ông T

### Tập điều khiển bảng điều khiển bằng quyền hạn nhỏ

Bối cảnh: bạn muốn xem ruflo làm gì mà không lo nó tự ý hành động. Mở `/ruflo`, vào Settings → Claude control và chọn write + ask. Sau đó nhờ Claude:

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

Claude mở mục Missions và đặt mục tiêu, bạn xác nhận hành động tạo. Kiểm tra lại mục Missions và Overview. README lưu ý: tạo mission không có nghĩa tính năng đã được làm xong. Nếu cần dừng, bấm Take back control.

### Theo dõi chi phí và token khi giao việc dài

Bối cảnh: bạn là người làm kinh doanh đang thử giao việc cho AI và lo hoá đơn. Bảng điều khiển hiển thị workflow, agent, model, token và chi phí cạnh Claude Code. README cũng có plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí). Cài theo cùng cú pháp plugin:

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

Bạn dùng nó để biết một lần chạy tốn bao nhiêu trước khi giao việc lớn hơn.

### Dùng ruflo với Codex hoặc công cụ khác

Bối cảnh: nhóm bạn dùng Codex thay vì Claude Code. Không cần cài vào dự án, chỉ cần khai báo MCP server như phần trên (command `npx`, arguments `["-y", "ruflo@latest", "mcp", "start"]`). Khi đó client của bạn gọi được các công cụ ruflo qua MCP.

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

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

Đường plugin cần Claude Code 2.1.287 trở lên, còn lệnh `claude plugin install` ở terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code, rồi gõ lại. Nhớ là các lệnh bắt đầu bằng `/plugin` gõ trong Claude Code, không phải trong terminal.

### npx báo lỗi phiên bản Node

`package.json` yêu cầu Node 20 trở lên. Chạy `node --version` để kiểm tra. Nếu thấp hơn, hãy cài bản Node mới hơn rồi chạy lại lệnh `init`.

### Cài xong mà Claude Code không thấy agent hay công cụ

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 Claude Code trong đúng thư mục bạn đã chạy `init`. Với plugin, chạy `/reload-plugins`.

### Tên công cụ MCP khác với tài liệu

README cho biết hai đường cài đặt đặt tên khác nhau. Plugin `ruflo-core` đăng ký công cụ dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, còn đường CLI dùng tên ngắn như `memory_store`. Nếu làm theo hướng dẫn dùng tên ngắn mà không chạy, hãy kiểm tra bạn đang cài bằng đường nào. Muốn đủ bộ với tên theo CLI thì dùng `npx ruflo@latest init`.

### Plugin bị nạp hai lần

Với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`, README dặn chỉ cài từ một marketplace (hoặc marketplace gốc của nó, hoặc `ruflo`). Cài từ cả hai nơi thì mod và lệnh bị nạp hai lần. Nếu thấy lệnh trùng, hãy gỡ một bản.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Có đường nhẹ (plugin, không thêm tệp vào dự án) và đường đầy đủ (CLI). Làm việc với cả Claude Code lẫn Codex. Có bảng điều khiển để theo dõi chi phí và kết quả. Hệ thống quyền Claude control đặt mặc định ở mức thấp (read + ask), đây là thiết kế an toàn. Giấy phép MIT và repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Bề mặt tính năng rất rộng (48 plugin, hàng trăm công cụ) nên người mới dễ bị ngợp. Mod chạy với quyền tài khoản của bạn và không có sandbox. README tự lưu ý rằng một số bản demo dùng dữ liệu mẫu và không chứng minh swarm hay bộ nhớ đã hoàn thành việc thật. Phần học và bộ nhớ vẫn cần embedding và cấu hình. Các thông tin về hệ điều hành hỗ trợ và chi phí API thì mình chưa có.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code làm việc nhỏ lẻ, dùng thẳng Claude Code là đủ. Nếu chỉ muốn thử một vài lệnh, hãy cài đúng một plugin thay vì cả bộ. Khi cần dùng thật cho dự án quan trọng, hãy bắt đầu ở mức quyền thấp, thử trên một dự án nháp trước, và đọc `SECURITY.md` trong repo.

## 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 mã nguồn dùng tự do. Tuy nhiên ruflo chạy trên Claude Code, Codex hoặc nhà cung cấp AI khác, và chi phí của các dịch vụ đó nằm ngoài tư liệu mình có. Bảng điều khiển hiển thị token và chi phí để bạn theo dõi.

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

Cần Node.js 20 trở lên và thường là Claude Code. Riêng đường cài plugin cần Claude Code 2.1.287 trở lên. README phần mình có không nói về API key riêng hay GPU cho ruflo.

### ruflo cài thế nào cho 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 trong cùng thư mục. Gõ `/ruflo` để mở bảng điều khiển.

### Cài plugin và chạy npx init khác nhau thế nào?

Plugin nhẹ hơn: không thêm tệp vào dự án, không cài hook, chỉ có lệnh slash, skill và định nghĩa agent. Đường `npx ruflo init` cho đầy đủ: agent, lệnh, skill, MCP server, hook, daemon, và thêm các thư mục như `.claude/` vào dự án. README gợi ý đường CLI cho dùng thật.

### Có dùng được với Codex hoặc công cụ không phải Claude Code không?

Có. README nói Codex và client MCP khác dùng được bằng cách cấu hình command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Ngoài ra có lệnh `npx ruflo init --grok` cho Grok Build.

### Để Claude điều khiển bảng điều khiển có an toàn không?

README mô tả bốn mức quyền (read, write, manage, full) và hai chế độ duyệt (ask, 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ả ở auto. Bạn có thể bấm Take back control bất cứ lúc nào. Riêng các mod thì không chạy trong sandbox, nên hãy đọc code trước khi cài.

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

Tư liệu mình có không nói rõ về hệ điều hành hỗ trợ. Hiện chỉ biết yêu cầu Node 20 trở lên. Bạn nên xem thêm thư mục docs/ trong repo hoặc thử trên một dự án nháp trước.
