# 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à một agent harness: lớp công cụ bao quanh Claude Code hoặc Codex để thêm agent chuyên biệt, bộ nhớ qua các phiên, hook và MCP server. Bạn dùng nó để giao việc cho cả một nhóm agent phối hợp thay vì chỉ một AI. Cài khá đơn giản: cần Node 20 trở lên và chạy một lệnh npx trong thư mục dự án.

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

Ruflo là một "agent harness" mã nguồn mở: lớp công cụ đặt quanh Claude Code hoặc Codex để AI không chỉ viết code mà còn có thêm agent chuyên biệt, bộ nhớ, vòng lặp tự cải thiện và các lớp kiểm soát. Repo này ban đầu có tên Claude Flow, sau đó đổi sang Ruflo. Hiện có khoảng 81.582 sao và 9.607 fork trên GitHub, giấy phép MIT, viết chủ yếu bằng TypeScript.

Vấn đề nó giải quyết khá quen thuộc. Khi dùng Claude Code, bạn thường giao việc cho một AI duy nhất, mỗi phiên làm việc bắt đầu lại từ đầu, và không có công cụ nào cho bạn thấy AI đang làm gì, tốn bao nhiêu token. Ruflo thêm phần "hệ thần kinh" cho Claude Code: nhiều agent có thể chia việc theo nhóm (swarm), ghi nhớ kinh nghiệm giữa các phiên, và có bảng điều khiển để bạn theo dõi.

Ai nên dùng? Lập trình viên đã dùng Claude Code hoặc Codex và muốn giao những việc lớn hơn như rà soát cả repo, viết test, ghi lại thay đổi. Người mới cũng thử được, vì README nói rõ bạn không cần học hết hàng trăm công cụ bên trong: sau `init`, cứ dùng Claude Code như bình thường, phần còn lại chạy ngầm. Điểm đáng giá nhất là cách cài chỉ một lệnh, kèm lựa chọn cài dạng plugin không để lại file nào trong dự án.

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

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

README mô tả Ruflo bằng công thức "Agent = Model + Harness": model viết, còn harness cung cấp công cụ, bộ nhớ, vòng lặp, sandbox và kiểm soát để model làm việc thật. Ruflo là phần harness đó. Dưới đây là các nhóm tính năng chính, giải thích theo lợi ích thực tế.

**Nhiều agent chuyên biệt, làm việc theo nhóm.** README nhắc tới hơn 100 agent chuyên biệt (bảng so sánh cài đặt ghi 98 agent). Bạn có thể yêu cầu một "swarm" xử lý một việc lớn, ví dụ tìm module rủi ro nhất, viết test, rồi tóm tắt thay đổi. Lợi ích: việc lớn được chia nhỏ thay vì dồn hết vào một cuộc hội thoại dài.

**Bộ nhớ qua các phiên.** Ruflo có bộ nhớ tự học và tích hợp tìm kiếm vector (RAG). Agent nhớ được kinh nghiệm từ các task trước, nên bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở phiên mới. README có lưu ý trung thực: phần học này là mô hình khái niệm, việc 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 cấu hình.

**Hook tự định tuyến.** Sau `init`, hệ thống hook tự chọn cách xử lý task, học từ các mẫu thành công và điều phối agent ngầm. Bạn không phải gọi từng công cụ bằng tay.

**MCP server.** Ruflo đi kèm MCP server nên Codex hoặc bất kỳ client MCP nào cũng nối vào được. README ghi có 406 công cụ MCP và 61 lệnh CLI, nhưng bạn không cần nhớ chúng.

**Bảng điều khiển (console) ngay cạnh Claude Code.** Bạn theo dõi 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, so sánh. Có thể mở bằng lệnh `/ruflo` trong Claude Code, hoặc chạy riêng trong terminal bằng `npx ruflo tui`.

**Cho 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 các mức `read`, `write`, `manage`, `full`, và chế độ 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á huỷ vẫn phải xác nhận kể cả khi để `auto`.

**48 plugin theo nhóm.** Ví dụ `ruflo-swarm` (phối hợp nhiều agent), `ruflo-testgen` (tìm test còn thiếu và tạo test), `ruflo-security-audit` (quét lỗ hổng), `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí), `ruflo-docs` (tạo và duy trì tài liệu), `ruflo-rag-memory` (truy xuất thông minh). Bạn chỉ cài cái mình cần.

**Federation.** Agent trên các máy khác nhau có thể trao đổi an toàn với nhau. Tính năng này dành cho người dùng nâng cao, người mới chưa cần quan tâm.

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

Theo tư liệu, bạn cần:

- **Node.js 20.0.0 trở lên.** `package.json` của repo yêu cầu `>=20.0.0`, và lệnh cài dùng `npx` đi kèm Node.
- **Claude Code** nếu bạn đi theo đường chính (README hướng dẫn mở Claude Code trong cùng thư mục dự án sau khi `init`). Với Codex hoặc client MCP khác, bạn nối vào MCP server của Ruflo.
- **Claude Code phiên bản 2.1.287 trở lên** nếu muốn cài theo kiểu plugin (marketplace). Lệnh `claude plugin install` từ terminal cần phiên bản 2.1.292 trở lên.
- **Một thư mục dự án** để chạy lệnh `init`.

Tư liệu không nói rõ về hệ điều hành, yêu cầu GPU hay dung lượng ổ đĩa, và README phần được cung cấp cũng chưa nói về API key riêng. Phần nào cần key thì bạn xem thêm trong tài liệu của repo (thư mục `docs/` và file `CLAUDE.md`).

```note
Mods của Ruflo chạy với quyền của tài khoản bạn và không nằm trong sandbox. README khuyên đọc code trước khi cài. Ngoài ra hãy giữ Claude control ở mức mặc định (read + ask) cho tới khi bạn hiểu rõ nó làm gì.
```

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

README đưa ra ba đường: cài vào dự án bằng `npx` (đường chính), cài plugin cho Claude Code (không thêm file vào dự án), và nối MCP cho Codex hoặc client khác. Mình đi theo đường chính trước.

```steps
- Kiểm tra Node | Chạy node -v và chắc chắn là 20 trở lên
- Mở terminal trong thư mục dự án | Đứng đúng thư mục bạn muốn thêm Ruflo vào
- Chạy init | npx ruflo@latest init để thêm agent, hook, bộ nhớ, 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
- Giao thử một việc thật | Gõ một yêu cầu dùng swarm để rà soát repo
```

### Kiểm tra phiên bản Node

Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) và chạy:

```bash
node -v
```

Nếu kết quả bắt đầu bằng `v20` hoặc cao hơn là ổn. Nếu thấp hơn, bạn cần nâng Node trước, vì `package.json` của Ruflo yêu cầu Node từ 20.0.0.

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

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

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

Thay phần sau `cd` bằng đường dẫn thật tới dự án của bạn.

### 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 bản 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 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 như `.claude/`, `.claude-flow/` và file `CLAUDE.md` trong workspace. Nếu bạn thích cài theo kiểu hỏi đáp từng bước, README có lệnh:

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

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

Mở Claude Code trong chính thư mục vừa chạy `init`. README cho biết Claude Code sẽ nhận các thành phần này ở lần khởi động kế tiếp, nên nếu Claude Code đang mở sẵn, hãy đóng và mở lại. Sau đó thử một yêu cầu thật, đây là prompt 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ách khác: cài dạng plugin cho Claude Code

Nếu bạn không muốn thêm file nào vào dự án, README có đường plugin. Đường này cài công cụ lõi, bảng điều khiển và các mod, và không thêm file vào dự á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
```

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 ý từ README: đường plugin nhẹ hơn, chủ yếu cho slash command và định nghĩa agent. Muốn có toàn bộ vòng làm việc (98 agent, hơn 60 lệnh, 30 skill, MCP server, hook, daemon) thì dùng `npx ruflo@latest init`.

### Cách khác: Codex hoặc client MCP

Với Codex hoặc client MCP khác, README hướng dẫn cấu hình **command** là `npx` và **arguments** là `["-y", "ruflo@latest", "mcp", "start"]`. Hoặc bạn chạy trực tiếp:

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

Cách ghi cấu hình này vào từng client cụ thể (tên file, vị trí) README phần được cung cấp chưa nêu; bạn xem tài liệu của client bạn dùng.

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

Có vài dấu hiệu theo README để biết cài thành công:

- Lệnh `npx ruflo@latest init` chạy xong mà không báo lỗi, và trong thư mục dự án xuất hiện các thư mục như `.claude/` và `.claude-flow/` cùng file `CLAUDE.md`.
- Sau khi mở lại Claude Code, bạn gõ `/ruflo` và thấy bảng điều khiển (cockpit) hiện ra.
- Với đường plugin, mở `/plugin` và kiểm tra các mod có xuất hiện ở dòng "active mods".
- Muốn thử không cần Claude Code, chạy giao diện terminal độc lập:

```bash
npx ruflo tui
```

Thêm `--plain` nếu bạn muốn in ra một khung hình duy nhất, tiện cho script.

Bài thử có kiểm chứng rõ ràng nhất trong README là tạo một "mission". Vào Settings → Claude control, chọn write + ask, rồi yêu cầu Claude: "Create a mission to add a dark mode toggle. Show me the mission and its status." Bạn xác nhận hành động tạo, sau đó kiểm tra mục Missions có mục tiêu đó và Overview có 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.

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

Phần này mình bám đúng những gì README mô tả. Kết quả thực tế sẽ tuỳ dự án và model bạn dùng.

### Lập trình viên rà soát một repo lạ

Bạn vừa nhận một dự án cũ, không ai nhớ module nào dễ hỏng. Sau khi `init` và mở lại Claude Code, bạn dán prompt 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 dùng nhóm agent để chỉ ra module rủi ro nhất, viết test cho nó và tóm tắt các thay đổi. Bạn vẫn nên đọc lại test được sinh ra trước khi chấp nhận, vì AI có thể viết test chưa sát thực tế.

> Agent = Model + Harness: model 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

### Trưởng nhóm muốn theo dõi chi phí và tiến độ

Bạn làm việc với Claude Code hằng ngày và muốn biết agent nào đang chạy, tốn bao nhiêu token. Cài đường plugin rồi mở console bằng `/ruflo`. Theo README, console cho bạn theo dõi workflow, agent, model, token và chi phí cạnh Claude Code, đồng thời mở log, tìm kiếm và so sánh các lần chạy. Nếu cần cảnh báo ngân sách, README có plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí), cài bằng cú pháp `/plugin install <tên>@ruflo` giống các plugin khác.

### Người mới thử cho Claude điều khiển bảng điều khiển có kiểm soát

Bạn chưa quen với agent tự chạy và muốn thử an toàn. Làm theo kịch bản README: đặt Claude control ở mức write + ask, yêu cầu tạo một mission "add a dark mode toggle", rồi tự bấm xác nhận khi console hỏi. Muốn dừng ngay, bấm **Take back control**; README nói sau đó mọi lời gọi công cụ console của Claude sẽ bị từ chối cho tới khi bạn khôi phục quyền. Kết quả: bạn thấy rõ ranh giới "Claude được làm gì, bạn duyệt gì" trước khi cho nó nhiều quyền hơn.

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

Bạn đang dùng Codex hoặc một ứng dụng hỗ trợ MCP và vẫn muốn có bộ nhớ và điều phối agent của Ruflo. Cấu hình server MCP với command `npx` và arguments `["-y", "ruflo@latest", "mcp", "start"]`. Khi đó công cụ của bạn gọi được các công cụ MCP của Ruflo mà không cần thiết lập dự án. README có nhắc cả hướng Grok Build (`npx ruflo init --grok`, có thể thêm `--dry-run` để xem trước), nhưng đó là phần nâng cao, bạn đọc thêm hướng dẫn riêng trong repo.

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

**Báo lỗi khi chạy `npx` hoặc có hành vi lạ.** Nguyên nhân dễ gặp nhất là Node cũ. Chạy `node -v`; nếu thấp hơn 20 thì nâng Node rồi chạy lại. Đây là yêu cầu có trong `package.json`.

**Mở Claude Code nhưng không thấy gì mới.** README nói Claude Code nhận agent, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Hãy đóng hẳn Claude Code rồi mở lại, và chắc chắn bạn mở nó trong đúng thư mục đã chạy `init`. Nếu chạy `init` nhầm thư mục, các file đã nằm sai chỗ, bạn nên kiểm tra thư mục đó trước khi dọn.

**Lệnh `/plugin` không chạy hoặc không tìm thấy plugin.** Đường plugin cần Claude Code 2.1.287 trở lên (lệnh `claude plugin install` từ terminal cần 2.1.292 trở lên). Hãy nâng Claude Code, rồi gõ `/reload-plugins` sau khi cài.

**Plugin bị nạp hai lần.** README cảnh báo với các plugin ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`: chỉ cài từ một marketplace duy nhất (hoặc marketplace gốc của plugin, hoặc `ruflo`). Cài từ cả hai thì mod và lệnh bị nạp hai lần. Hãy gỡ một bên.

**Claude bị từ chối khi điều khiển console.** Đây thường là thiết kế chứ không phải lỗi: mức mặc định là read + ask, và các hành động vượt quyền, hay liên quan mạng, chi tiêu, phá huỷ, đều bị từ chối hoặc đòi xác nhận. Nếu bạn cần cho phép thêm, hãy tăng mức quyền từng nấc trong Settings → Claude control, và đọc nhật ký hành động trực tiếp. Nếu bạn đã bấm Take back control thì phải khôi phục quyền mới dùng lại được.

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

**Điểm mạnh.** Cài đặt gọn: một lệnh `npx ruflo@latest init` là đủ để bắt đầu. Có đường nhẹ hơn là plugin không thêm file vào dự án. Hệ sinh thái rộng (48 plugin, MCP server, bảng điều khiển, bộ nhớ), giấy phép MIT, dự án vẫn được cập nhật trong vài tháng gần đây, và cộng đồng lớn. README cũng khá thẳng thắn về giới hạn, ví dụ ghi rõ các đoạ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.** Ruflo khá đồ sộ: hàng trăm công cụ MCP, hàng chục lệnh và plugin, nên người mới dễ choáng nếu cố tìm hiểu hết. Nó bổ sung các tầng như hook, daemon, file cấu hình vào dự án, nên bạn cần xem lại những gì `init` thêm. Mod chạy với quyền tài khoản của bạn và không có sandbox. Phần học của agent là khái niệm, không nên kỳ vọng nó tự thông minh lên thần kỳ. Tư liệu tôi có chưa nêu chi phí API, yêu cầu phần cứng hay hỗ trợ từng hệ điều hành, nên bạn tự kiểm tra trước khi triển khai nghiêm túc.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần một AI hỗ trợ viết code đơn giản, Claude Code hoặc Codex đứng một mình là đủ, không cần thêm harness. Nếu chỉ cần một tính năng riêng như quét bảo mật hay sinh test, hãy cài đúng một plugin thay vì toàn bộ. Còn nếu bạn muốn thử giao việc lớn cho một nhóm agent, có bảng điều khiển để giám sát và đặt giới hạn rõ ràng, Ruflo là một lựa chọn đáng thử. Cứ bắt đầu từ đường nhẹ nhất, mức quyền thấp nhất, rồi nới 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 mã nguồn dùng được miễn phí. Tuy nhiên tư liệu chưa nói về chi phí của Claude Code, Codex hay các nhà cung cấp AI mà Ruflo gọi tới, nên bạn cần tự kiểm tra gói dịch vụ bạn đang dùng. Ruflo có plugin ruflo-cost-tracker để theo dõi token và đặt ngân sách.

### Ruflo cần phiên bản Node nào?

package.json của repo yêu cầu Node từ 20.0.0 trở lên. Bạn kiểm tra bằng lệnh node -v. Nếu thấp hơn, hãy nâng Node trước khi chạy npx ruflo@latest init.

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

Có, nếu dùng npx ruflo@latest init. README ghi lệnh này thêm các thư mục như .claude/, .claude-flow/ và file CLAUDE.md cùng hook, MCP server vào dự án. Nếu không muốn thêm file nào, README có đường cài plugin cho Claude Code với "zero file" trong workspace, nhưng bộ tính năng ít hơn.

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

Được. README nói Codex và các 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"]. Chi tiết cách nhập cấu hình vào từng công cụ thì tư liệu chưa ghi, bạn xem tài liệu của công cụ đó.

### Claude có tự ý làm những việc nguy hiểm không?

README mô tả cơ chế giới hạn: Claude control có các mức read, write, manage, full và chế độ duyệt ask hoặc auto, mặc định là read + ask. Hành động vượt quyền bị từ chối, còn hành động liên quan mạng, chi tiêu hoặc phá huỷ cần xác nhận kể cả ở chế độ auto. Bạn có thể bấm Take back control để dừng. Riêng các mod thì README cảnh báo chúng chạy với quyền tài khoản của bạn, không có sandbox.

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

Tư liệu tôi có chưa nêu rõ hỗ trợ hệ điều hành hay yêu cầu GPU. Điều chắc chắn là cần Node 20 trở lên và lệnh cài dùng npx. Bạn nên xem thêm tài liệu trong thư mục docs/ của repo hoặc tự thử trên máy mình.

### Ruflo khác gì dùng Claude Code đơn thuần?

Claude Code là công cụ để AI viết code. Ruflo là lớp harness bao quanh nó, thêm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook định tuyến, MCP server và bảng điều khiển theo dõi token và chi phí. Nếu bạn chỉ cần trợ lý code đơn giản, Claude Code một mình có thể là đủ.
