# Ruflo: điều phối nhiều 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", tức lớp điều phối bao quanh Claude Code và Codex. Nó thêm nhiều agent chuyên biệt, bộ nhớ qua các phiên làm việc, hook và máy chủ MCP. 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-10-11 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-nhieu-agent-claude-code-codex-huong-dan

Ruflo là một "agent harness" (bộ khung điều phối) dành cho Claude Code và Codex. Hiểu đơn giản: mô hình AI lo phần viết, còn Ruflo lo phần còn lại, gồm công cụ, bộ nhớ, vòng lặp làm việc và các giới hạn kiểm soát. Nó trước đây tên là Claude Flow, do Reuven Cohen (rUv) xây dựng.

Vấn đề nó giải quyết khá quen thuộc. Khi dùng Claude Code cho việc lớn, bạn thường phải tự chia nhỏ nhiệm vụ, tự nhắc lại bối cảnh, và mỗi phiên mới lại quên sạch những gì đã làm. Ruflo gắn thêm nhiều agent chuyên biệt có thể phối hợp thành "swarm" (đàn agent), cùng bộ nhớ lưu lại giữa các phiên. Nhờ vậy bạn vẫn dùng Claude Code như bình thường, còn việc điều phối chạy ngầm phía sau.

Bạn nên thử nếu là lập trình viên (kể cả mới vào nghề) đang dùng Claude Code hoặc Codex và muốn giao việc dài hơi như rà soát repo, viết test, tóm tắt thay đổi. Điểm đáng giá nhất là cài rất nhanh, chỉ một lệnh. Repo hiện có khoảng 81.582 sao và 9.607 fork, giấy phép MIT.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | Ruflo là bộ khung điều phối cho Claude Code và Codex: thêm agent, bộ nhớ, hook và máy chủ MCP vào dự án chỉ bằng một lệnh npx.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README giới thiệu rất nhiều thứ. Dưới đây là những phần đáng chú ý nhất với người mới, đã gom lại theo lợi ích thực tế.

**Nhiều agent làm việc như một đội.** Sau khi cài, bạn có hàng chục agent chuyên biệt (README nói 98 agent ở đường cài bằng CLI). Chúng có thể tự chia việc thành swarm. Bạn chỉ cần nói "dùng swarm của ruflo để rà soát repo" thay vì tự giao việc cho từng agent.

**Hook tự định tuyến việc.** 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`, bạn cứ dùng Claude Code như thường. Hệ thống hook tự chọn cách xử lý, học từ các mẫu thành công và điều phối agent ở nền.

**Bộ nhớ qua nhiều phiên.** Ruflo có bộ nhớ vector để agent nhớ lại kinh nghiệm cũ, không phải bắt đầu từ con số không mỗi lần. README ghi rõ phần truy xuất vector cục bộ có thể chạy mà 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 (console) ngay cạnh Claude Code.** Bạn xem được workflow, agent, mô hình, token và chi phí. Bạn cũng mở được log và kết quả của từng lần chạy, tìm kiếm, tìm lỗi, phát lại và so sánh. Mở bằng lệnh `/ruflo` trong Claude Code, hoặc chạy riêng bằng `npx ruflo tui` ngoài terminal.

**Cho Claude điều khiển bảng điều khiển, nhưng bạn đặt giới hạn.** Trong Settings → Claude control, bạn chọn mức `read`, `write`, `manage` hoặc `full`, cùng chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. Các thao tác liên quan mạng, chi tiêu và phá huỷ vẫn phải xác nhận kể cả ở chế độ `auto`. Có nút **Take back control** để lấy lại quyền ngay.

**Hệ plugin lớn.** Có 48 plugin trong marketplace (cộng 3 plugin bên ngoài), chia nhóm như: điều phối (`ruflo-swarm`, `ruflo-autopilot`), bộ nhớ (`ruflo-agentdb`, `ruflo-rag-memory`), kiểm thử (`ruflo-testgen`, `ruflo-browser`), bảo mật (`ruflo-security-audit`, `ruflo-aidefence`), theo dõi chi phí (`ruflo-cost-tracker`) và nhiều nhóm khác. Bạn chỉ cài cái mình cần.

**Dùng được ngoài Claude Code.** Codex và các client MCP khác kết nối được qua lệnh `npx -y ruflo@latest mcp start`. README cũng có tuỳ chọn `--grok` cho Grok Build.

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

Tư liệu repo nêu khá ít yêu cầu, và mình chỉ ghi những gì có trong đó:

- **Node.js từ 20.0.0 trở lên.** Đây là yêu cầu trong `package.json`. Lệnh `npx` đi kèm Node nên bạn không cần cài thêm gì.
- **Claude Code** nếu bạn đi đường cài bằng `init` (README bảo mở Claude Code trong cùng thư mục sau khi cài).
- **Claude Code 2.1.287 trở lên** nếu chọn đường cài chỉ bằng plugin. Lệnh `claude plugin install` trong terminal cần bản 2.1.292 trở lên.
- **Một thư mục dự án** để chạy lệnh trong đó.

README phần mình có không nói rõ về hệ điều hành, GPU hay API key bắt buộc. Các thông tin đó chưa có trong tư liệu mình đọc được, nên bạn xem thêm trong README và thư mục `docs/` của repo.

```note
Các mod (ruflo-mods và tương tự) chạy với đúng quyền tài khoản của bạn và không được cách ly (sandbox). README khuyên đọc mã của chúng trước khi cài. Hãy làm theo lời khuyên này, nhất là khi dùng máy làm việc thật.
```

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

Ruflo có hai đường cài với phạm vi rất khác nhau. Đường dùng lệnh `init` cho trải nghiệm đầy đủ. Đường plugin gọn hơn, không thêm file nào vào dự án.

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

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

Mở terminal (PowerShell trên Windows, hoặc Terminal trên máy khác) rồi di chuyển vào thư mục dự án của bạn. Đây là chỗ người mới hay vấp nhất: lệnh `init` ghi file vào thư mục hiện tại, nên nếu đứng nhầm chỗ, file sẽ nằm sai dự án.

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

Thay `duong-dan-toi-thu-muc-du-an` 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 trong README:

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

Lệnh này thêm agent, hook, bộ nhớ và máy chủ MCP của Ruflo vào dự án. README cho biết các file được thêm gồm `.claude/`, `.claude-flow/`, `CLAUDE.md`, các file hỗ trợ và settings. Nếu thư mục của bạn đã có `CLAUDE.md` riêng, hãy sao lưu trước khi chạy để khỏi mất ghi chú cũ.

Muốn thiết lập có hướng dẫn từng câu hỏi, README có lệnh:

```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, hook, bộ nhớ và MCP server ở lần khởi động tiếp theo. Nếu bạn đang mở sẵn một phiên Claude Code từ trước, hãy đóng và mở lại.

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

Cách này không thêm file nào vào dự án. Nó cài công cụ lõi, bảng điều khiển và các mod. Chạy 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 ý README so sánh hai đường: plugin chỉ cho slash command, vài skill và định nghĩa agent, không cài hook. Muốn dùng đầy đủ như tài liệu mô tả thì dùng `init`.

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

Với Codex hay công cụ hỗ trợ MCP, bạn cấu hình **command** là `npx` và **arguments** là `["-y", "ruflo@latest", "mcp", "start"]`. Cách nhập cụ thể tuỳ từng ứng dụng, nên bạn xem tài liệu của chính client đó để biết chỗ điền.

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

### Cách khác: chạy giao diện terminal riêng

Bảng điều khiển chạy được độc lập, không cần Claude Code:

```bash
npx ruflo tui
```

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

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

Cách kiểm tra theo tư liệu:

1. **Sau `init`:** mở Claude Code trong thư mục dự án. Bạn nên thấy các thư mục `.claude/` và `.claude-flow/` cùng file `CLAUDE.md` đã xuất hiện trong dự án.
2. **Sau khi cài plugin:** gõ `/plugin` trong Claude Code. README nói các mod đã cài sẽ hiện trong dòng "active mods".
3. **Mở bảng điều khiển:** gõ `/ruflo`. Nếu cửa sổ console hiện ra, cài đặt đã ổn.
4. **Thử bằng một việc nhỏ:** dùng bài thử trong README, tức là yêu cầu Claude tạo một "mission", rồi kiểm tra mục Missions và Overview có ghi lại hành động đó không.
5. **Không muốn đụng vào dự án thật?** Thêm `--dry-run` vào lệnh để xem trước. README ghi cờ này cho trường hợp `init --grok`. Với lệnh `init` thường, README chưa ghi, nên bạn thử trên thư mục tạm trước.

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

Bạn chỉ cần nhớ một điều: cứ nói chuyện với Claude Code như bình thường. Phần điều phối chạy ở nền. Dưới đây là vài tình huống bám theo đúng những gì README mô tả.

### Rà soát một repo thừa kế

**Bối cảnh:** bạn mới nhận một dự án cũ từ đồng nghiệp, không ai nhớ rõ phần nào dễ hỏng.

**Cách làm:** chạy `npx ruflo@latest init` trong thư mục dự án, mở lại Claude Code rồi dán câu lệnh mẫu của chính 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ả:** Claude dùng swarm để tìm module rủi ro nhất, viết test cho nó và tóm tắt những gì đã thay đổi. Bạn vẫn nên đọc lại test và các thay đổi trước khi giữ lại.

> Agent không chỉ chạy, chúng phải phối hợp được với nhau — còn bạn cứ tập trung viết code.
>
> — Ông T

### Theo dõi chi phí khi để agent chạy lâu

**Bối cảnh:** bạn giao việc dài và lo token bị đốt mà không hay.

**Cách làm:** bảng điều khiển hiển thị workflow, agent, mô hình, token và chi phí ngay cạnh Claude Code. Mở bằng `/ruflo`. README cũng có plugin `ruflo-cost-tracker` để theo dõi token, đặt ngân sách và nhận cảnh báo chi phí:

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

**Kết quả:** bạn thấy được tiêu hao ngay trong lúc chạy, thay vì chờ hoá đơn cuối tháng.

### Để Claude thao tác bảng điều khiển có kiểm soát

**Bối cảnh:** bạn muốn thử giao việc quản lý mission cho Claude nhưng ngại nó làm quá tay.

**Cách làm:** theo README, mở `/ruflo`, vào **Settings → Claude control**, chọn mức **write + ask**. Rồi nhập 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 thao tác tạo đang chờ trong console.

**Kết quả:** mục Missions có mục tiêu mới và Overview ghi lại hành động. README nhắc rõ: tạo mission không có nghĩa tính năng đã được viết. Nếu cần dừng, bấm **Take back control**.

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

**Bối cảnh:** nhóm bạn dùng Codex thay vì Claude Code.

**Cách làm:** không cần chạy `init` cho dự án. Chỉ cần trỏ client MCP tới `npx -y ruflo@latest mcp start` như đã nêu ở phần cài đặt.

**Kết quả:** client đó gọi được các công cụ MCP của Ruflo. README không mô tả chi tiết kết quả cho từng client, nên bạn thử trên một dự án nhỏ trước.

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

Tư liệu README mình đọc không có mục xử lý lỗi riêng. Dưới đây là những lỗi rất dễ gặp với loại công cụ này, kèm cách xử lý an toàn.

**Lệnh `npx` báo lỗi hoặc không chạy.** Thường do Node quá cũ. Repo yêu cầu Node từ 20.0.0 trở lên. Kiểm tra bằng `node --version`, nếu thấp hơn thì nâng cấp Node rồi chạy lại.

**Cài xong mà Claude Code không thấy agent hay công cụ mới.** README nói Claude Code nhận cấu hình ở lần khởi động tiếp theo. Hãy đóng hẳn Claude Code rồi mở lại trong đúng thư mục đã chạy `init`. Với plugin, thử `/reload-plugins` rồi mở `/plugin` để xem danh sách.

**Lệnh `/plugin install` không nhận hoặc báo thiếu.** Đườ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. Cập nhật Claude Code nếu bản của bạn cũ hơn.

**Cài cùng một plugin từ hai marketplace.** README cảnh báo với các plugin ngoài như `agentic-qe-fleet`, `agentdb`, `agentic-flow`: cài từ cả hai nguồn thì mod và lệnh bị nạp hai lần. Chỉ chọn một nguồn.

**Lẫn tên công cụ giữa hai đường cài.** Plugin `ruflo-core` đăng ký MCP server riêng với tên dạng `mcp__plugin_ruflo-core_ruflo__memory_store`, không phải tên gọn như `memory_store` ở đường CLI. Nếu hướng dẫn nào bảo gọi tên khác với cái bạn thấy, hãy kiểm tra xem bạn đang dùng đường cài nào.

**Claude thao tác quá mức bạn muốn.** Hạ mức quyền trong Settings → Claude control về `read` và duyệt `ask`, hoặc bấm **Take back control**.

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

**Điểm mạnh.** Cài đặt rất nhanh, chỉ một lệnh. Bạn không phải học hàng trăm công cụ vì hook tự lo phần điều phối. Hệ plugin rộng, nên có thể chọn dần thứ cần dùng. Có bảng điều khiển để xem agent, token và chi phí, cùng cơ chế giới hạn quyền khi cho Claude tự thao tác. Repo cũng được cập nhật trong 3 tháng gần đây và dùng giấy phép MIT.

**Giới hạn.** Phạm vi của Ruflo rất lớn: 48 plugin, hàng trăm công cụ MCP. Người mới dễ bị ngợp nếu cố khám phá hết. Đường `init` thêm khá nhiều file vào dự án, nên cân nhắc thử trên một dự án nháp trước. README cũng tự nói rõ một số bản demo dùng dữ liệu mẫu và không chứng minh swarm đã hoàn thành việc thật. Hãy đánh giá bằng chính tác vụ của bạn. Các mod chạy không sandbox với quyền tài khoản của bạn. Những phần như hệ điều hành hỗ trợ hay yêu cầu phần cứng, mình chưa thấy trong tư liệu.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ muốn Claude Code làm vài việc nhỏ, rời rạc thì bản thân Claude Code là đủ, thêm Ruflo có thể thừa. Nếu bạn muốn một công cụ rất nhẹ, không thêm file vào dự án, hãy thử đường plugin của Ruflo với vài plugin thật cần thiết thay vì cài đầy đủ.

## 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 cùng Claude Code, Codex hoặc các nhà cung cấp AI khác, và chi phí của các dịch vụ đó nằm ngoài repo. Tư liệu mình có chưa nêu bảng giá, nên bạn kiểm tra gói của chính dịch vụ AI bạn dùng.

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

Bạn cần Node.js từ phiên bản 20.0.0 trở lên theo package.json, và Claude Code nếu dùng đường cài bằng init. Với đường chỉ cài plugin, README yêu cầu Claude Code 2.1.287 trở lên. Về GPU hay API key bắt buộc thì tư liệu mình đọc chưa nói rõ.

### Cài Ruflo bằng lệnh nào?

Chạy `npx ruflo@latest init` trong thư mục dự án, rồi mở lại Claude Code trong cùng thư mục. Nếu muốn thiết lập có hướng dẫn, dùng `npx ruflo@latest init wizard`. Còn nếu không muốn thêm file vào dự án, bạn có thể cài bằng plugin qua `/plugin marketplace add ruvnet/ruflo`.

### Ruflo có dùng được với Codex không?

Có. README nói Codex và các client MCP khác kết nối được qua command `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Cách điền vào từng ứng dụng tuỳ client, nên bạn xem tài liệu của client đó.

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

Claude Code lo phần viết và chỉnh code. Ruflo thêm lớp điều phối bên ngoài, gồm nhiều agent phối hợp thành swarm, bộ nhớ qua các phiên, hook tự định tuyến và bảng điều khiển theo dõi chi phí. Với việc nhỏ lẻ, Claude Code thuần có thể là đủ.

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

README nói mức mặc định hiện là read + ask, nghĩa là chỉ đọc và hỏi bạn trước. Các thao tác vượt mức quyền bị từ chối, còn thao tác liên quan mạng, chi tiêu và phá huỷ vẫn cần xác nhận kể cả ở chế độ auto. Bạn có thể bấm Take back control để dừng ngay.

### Có cần chạy Ruflo bên trong Claude Code không?

Không bắt buộc. Bảng điều khiển chạy riêng bằng `npx ruflo tui`, và thêm `--plain` để in một khung hình cho script. Còn các tính năng như hook và agent thì phát huy khi dùng cùng Claude Code hoặc client MCP.
