# 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 là một agent harness mã nguồn mở (giấy phép MIT, viết bằng TypeScript), vốn có tên Claude Flow. Nó bọc quanh Claude Code và Codex để thêm các agent chuyên biệt, swarm phối hợp, bộ nhớ qua nhiều phiên và bảng điều khiển theo dõi. 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-11-04 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ruflo-dieu-phoi-agent-ai-claude-code-codex-huong-dan-6

ruflo là một "agent harness" mã nguồn mở: lớp công cụ bọc quanh Claude Code và Codex để các AI này làm việc theo nhóm, nhớ được việc cũ và có bảng điều khiển để bạn theo dõi. 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.

Hiểu đơn giản thế này: mô hình AI là người viết code, còn harness là cái bàn làm việc xung quanh. Bàn đó có công cụ, bộ nhớ, vòng lặp kiểm tra và các giới hạn an toàn. README viết ngắn gọn là "Agent = Model + Harness", và ruflo chính là phần harness.

Ai nên dùng? Lập trình viên đang làm việc với Claude Code hoặc Codex và muốn giao những nhiệm vụ lớn hơn một câu lệnh đơn lẻ, ví dụ "review cả repo, viết test cho chỗ rủi ro nhất". Người làm văn phòng hoặc kinh doanh ít code vẫn có thể thử qua đường plugin, nhưng bạn cần quen với Claude Code trước. Điểm đáng giá nhất là bạn chỉ cần một lệnh `init`, sau đó cứ dùng Claude Code như bình thường. README nói hệ thống hook sẽ tự định tuyến tác vụ và học từ các lần làm thành công.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung (harness) gắn thêm agent, bộ nhớ, hook và MCP server cho Claude Code và Codex, 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 rất nhiều thứ, nhưng phần cốt lõi nằm trong vài nhóm sau.

- **Swarm và agent chuyên biệt.** Bạn giao một việc, các agent tự chia việc và phối hợp. README nói sau `init` bạn có 98 agent, hơn 60 lệnh và 30 skill. Lợi ích là một yêu cầu lớn được chia nhỏ, không dồn hết vào một phiên chat.
- **Bộ nhớ qua nhiều phiên.** Các plugin như `ruflo-agentdb`, `ruflo-rag-memory` và `ruflo-rvf` lưu và truy xuất lại trải nghiệm cũ. Nhờ vậy hôm sau bạn không phải giải thích lại bối cảnh dự án từ đầu.
- **Học từ kết quả.** README mô tả vòng học: bộ nhớ đưa kinh nghiệm hữu ích quay lại phần định tuyến. Chính README cũng ghi đây là luồng khái niệm, không phải bản ghi một lần chạy thật. Đừng kỳ vọng nó "thông minh lên" thần kỳ.
- **Bảng điều khiển (console).** Đây là "buồng lái" cạnh Claude Code. Bạn theo dõi quy trình, agent, model, token và chi phí, mở log của từng agent, tìm kiếm, phân loại lỗi, xem lại và so sánh các lần chạy.
- **Cho Claude lái, 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 hành động liên quan mạng, chi tiêu hoặc phá huỷ vẫn phải xác nhận ngay cả khi để `auto`. Có nút **Take back control** để dừng ngay.
- **48 plugin chia theo nhóm.** Có plugin cho kiểm thử (`ruflo-testgen`), bảo mật (`ruflo-security-audit`, `ruflo-aidefence`), theo dõi chi phí token (`ruflo-cost-tracker`), tài liệu (`ruflo-docs`), liên kết agent giữa nhiều máy (`ruflo-federation`) và nhiều nhóm khác. Bạn cài cái nào cần, không bắt buộc cài hết.
- **Dùng được với Codex và các MCP client khác.** Chỉ cần trỏ client đó tới `npx -y ruflo@latest mcp start`.

README nhắn riêng cho người mới: 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 bình thường.

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

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

- **Node.js từ phiên bản 20 trở lên** (`package.json` yêu cầu `>=20.0.0`). Lệnh `npx` đi kèm Node.
- **Claude Code**, nếu bạn dùng cách chính. Với đường cài bằng plugin, README yêu cầu Claude Code **2.1.287 trở lên**. Lệnh cài plugin 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 phép khai báo một lệnh MCP server.

Tư liệu chưa nói rõ hệ điều hành nào được hỗ trợ chính thức, cũng chưa nêu yêu cầu phần cứng hay GPU. Phần API key, README có nhắc rằng bộ nhớ và học tập cần embedding và các module học được cấu hình, nhưng không nói chi tiết phải điền key nào. Phần mô tả ruflo-ruvector có nhắc tìm kiếm tăng tốc GPU, nhưng đó là một plugin tuỳ chọn.

```note
Các "mod" của ruflo chạy với quyền tài khoản của bạn và không được cách ly (sandbox). README dặn đọc mã của mod trước khi cài. Mặc định Claude control ở mức read + ask, bạn hãy giữ nguyên mức này cho tới khi quen.
```

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

README chỉ ra nhiều đường cài. Phần này đi theo đường chính: lệnh `init` trong thư mục dự án. Đường plugin nhẹ hơn nằm ngay sau đó.

```steps
- Mở terminal đúng thư mục | vào thư mục dự án bạn muốn dùng ruflo
- Chạy init | gõ `npx ruflo@latest init` để thêm agent, hook, 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
- Mở bảng điều khiển | gõ `/ruflo` trong Claude Code
- Giao thử một việc thật | đưa một yêu cầu cụ thể cho Claude Code
```

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

Chỗ người mới hay vấp nhất là chạy lệnh sai chỗ. `init` thêm file vào thư mục hiện tại, nên bạn phải đứng đúng trong thư mục dự án. Nếu chưa có dự án, tạo một thư mục thử rồi `cd` vào đó.

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

Thay `duong-dan-toi-thu-muc-du-an` bằng đường dẫn thật trên máy 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. README nói lệnh này thêm agent, hook, bộ nhớ và MCP server của ruflo vào dự án. Phần bảng so sánh trong README ghi cách này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng các file hỗ trợ và settings trong dự án. Vì vậy hãy chạy trong một dự án có quản lý phiên bản (git) để dễ xem lại những gì đã thêm.

Nếu 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
```

Nếu dùng Grok Build, README có cờ `--grok` và cờ `--dry-run` để xem trước mà chưa ghi file:

```bash
npx ruflo init --grok
```

### Mở lại Claude Code và vào bảng điều khiển

README nói Claude Code sẽ nhận agent, hook và MCP server ở lần khởi động kế tiếp. Nếu đang mở sẵn Claude Code, hãy thoát và mở lại trong cùng thư mục. Sau đó gõ lệnh sau trong Claude Code để mở bảng điều khiển:

```text
/ruflo
```

### Cách khác: chỉ cài plugin, không thêm file vào dự án

Nếu chưa muốn ruflo ghi file vào dự án, dùng đường plugin. Chạy trong Claude Code (bản 2.1.287 trở lên):

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo
```

Các dòng này lần lượt thêm kho plugin của ruflo, cài lõi, bảng điều khiển và mod, nạp lại plugin rồi mở console. Theo README, đường này không thêm file nào vào dự án và không cài hook. Chỉ `ruflo-core` đăng ký MCP server riêng. Bạn sẽ có ít tính năng hơn so với `init`, và README nhận xét `init` mới là đường cho việc dùng nghiêm túc.

Từ terminal thường, trên Claude Code 2.1.292 trở lên:

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

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

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"]`. Nói cách khác, client sẽ chạy tương đương lệnh:

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

Chỗ điền command và arguments tuỳ từng client. README không chỉ vị trí file cấu hình, nên bạn xem tài liệu của client đang dùng.

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

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

1. **Gõ `/ruflo` trong Claude Code.** Nếu bảng điều khiển hiện ra thì cài đặt đã nhận.
2. **Mở `/plugin`** để xem các mod có nằm trong dòng "active mods" không (áp dụng khi bạn cài qua plugin). Nếu chưa thấy, chạy `/reload-plugins`.
3. **Chạy giao diện terminal độc lập**, không cần Claude Code:

```bash
npx ruflo tui
```

Thêm `--plain` nếu muốn in ra đúng một khung hình, hợp cho script:

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

README không nêu một dòng thông báo thành công cụ thể nào, nên dấu hiệu rõ nhất là console mở được và bạn thấy các trang như Missions, Overview, Learning, Security.

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

### Nhờ swarm review cả một repo (lập trình viên)

Bối cảnh: bạn vừa nhận một dự án cũ, không biết chỗ nào dễ hỏng. Sau khi `init` và mở lại Claude Code, bạn đưa đúng prompt mẫu trong 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 theo README: các 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 lại phần tóm tắt và xem diff trước khi giữ thay đổi. Công cụ nào cũng có thể làm sai.

> Bạn vẫn viết code như cũ, còn việc điều phối cứ để harness lo.
>
> — Ông T

### Tạo một "mission" bằng cách để Claude điều khiển console (người mới làm quen)

Bối cảnh: bạn muốn thử cho Claude thao tác trên console mà vẫn giữ quyền kiểm soát. README có kịch bản năm bước:

- Mở `/ruflo`, vào **Settings → Claude control**, chọn **write + ask**.
- Đưa yêu cầu cụ thể: "Create a mission to add a dark mode toggle. Show me the mission and its status."
- Khi Claude mở trang Missions và đặt mục tiêu, bạn xác nhận hành động tạo đang chờ.
- Kiểm tra mục tiêu có trong Missions và Overview có ghi lại hành động.
- Muốn dừng, bấm **Take back control**. Lần gọi sau của Claude sẽ bị từ chối tới khi bạn trả quyền.

Kết quả: bạn có một mission trong danh sách. README nhấn mạnh việc tạo mission không có nghĩa là tính năng đã được viết xong.

### Nối Codex hoặc công cụ MCP khác (người dùng nhiều công cụ AI)

Bối cảnh: bạn không dùng Claude Code mà dùng Codex hoặc một ứng dụng hỗ trợ MCP. Trong phần cấu hình MCP server của ứng dụng đó, điền:

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

Kết quả: ứng dụng khởi động MCP server của ruflo và có thể gọi công cụ của nó. Tên trường nhập liệu khác nhau theo từng ứng dụng, nên bạn đối chiếu với mục hướng dẫn MCP của chính ứng dụng.

### Theo dõi token và chi phí (người quản lý ngân sách AI)

Bối cảnh: bạn lo việc chạy nhiều agent làm tốn token. README liệt kê plugin `ruflo-cost-tracker` với mô tả "Track token usage, set budgets, get cost alerts". Theo mẫu cài plugin trong README, bạn có thể cài trong Claude Code:

```text
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-cost-tracker@ruflo
```

Bảng điều khiển cũng hiển thị token và chi phí cạnh Claude Code. Nếu lệnh cài báo lỗi tên plugin, mở `/ruflo market` (Plugin Catalog) để xem danh sách và cài từ đó.

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

### Chạy `npx` báo lỗi hoặc không chạy được

Nguyên nhân hay gặp là Node.js quá cũ. `package.json` yêu cầu Node từ 20 trở lên. Kiểm tra bằng `node --version`. Nếu thấp hơn, cập nhật Node rồi chạy lại lệnh `init`.

### Đã `init` nhưng Claude Code không thấy agent hay MCP

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 đúng trong thư mục đã chạy `init`. Chạy `init` ở thư mục khác với thư mục đang mở là lỗi rất dễ gặp.

### Lệnh `/plugin` hoặc `/ruflo` không có hiệu lực

Đường plugin cần Claude Code 2.1.287 trở lên (và 2.1.292 trở lên cho lệnh `claude plugin install`). Hãy cập nhật Claude Code. Sau khi cài plugin, chạy `/reload-plugins`.

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

Với các plugin bên ngoài như `agentic-qe-fleet`, `agentdb` và `agentic-flow`, README dặn chỉ cài từ **một** marketplace. Nếu bật từ cả hai nơi, mod và lệnh sẽ tải hai lần. Chọn một nguồn và gỡ nguồn còn lại.

### Claude từ chối thao tác trong console

Đây thường là thiết kế chứ không phải lỗi. Hành động vượt mức quyền bạn đặt sẽ bị từ chối. Hành động liên quan mạng, chi tiêu hoặc phá huỷ luôn cần xác nhận. Nếu cần, nâng mức từ `read` lên `write`, nhưng hãy giữ chế độ `ask` để tự duyệt từng bước.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Dùng được với cả Claude Code lẫn Codex. Có bảng điều khiển để nhìn thấy agent đang làm gì, tốn bao nhiêu token. Cơ chế giới hạn quyền cho Claude khá rõ ràng. Giấy phép MIT, và repo còn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Hệ thống rất lớn: hàng chục plugin, hàng trăm công cụ MCP. Người mới dễ choáng nên hãy bắt đầu từ `init` và một prompt đơn giản. Lệnh `init` thêm khá nhiều file vào dự án, bạn nên dùng nó trong dự án có git. Mod không được sandbox. README cũng thừa nhận một số đoạn minh hoạ dùng dữ liệu mẫu và không chứng minh việc swarm đã hoàn thành công việc thật hay bộ nhớ gọi lại đúng. Hãy tự kiểm tra kết quả trên dự án của mình.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần Claude Code trả lời vài câu hỏi hoặc sửa một file nhỏ, ruflo là thừa. Nếu bạn không dùng terminal hay Node, README chưa có đường cài nào dành cho bạn. Nếu cần thử nhẹ, hãy đi đường plugin trước (`ruflo-core`, `ruflo-console`), thấy hợp rồi mới chạy `init` cho dự án thật.

## 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. Tư liệu không nói gì về phí của ruflo. Chi phí thật sự đến từ các nhà cung cấp mô hình AI bạn kết nối, ví dụ gói Claude Code hay Codex của bạn.

### Cài ruflo cần những gì?

Cần Node.js từ phiên bản 20 trở lên và Claude Code (hoặc Codex hay một client MCP khác). Cách chính là chạy `npx ruflo@latest init` trong thư mục dự án. Đường cài bằng plugin cần Claude Code từ 2.1.287 trở lên.

### ruflo có cần GPU không?

Tư liệu không nêu yêu cầu GPU cho lõi của ruflo. Chỉ có plugin `ruflo-ruvector` được mô tả là tìm kiếm tăng tốc GPU, và đó là tuỳ chọn. Ngoài ra chưa có thông tin chi tiết về cấu hình phần cứng tối thiểu.

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

Tư liệu chưa nói rõ hệ điều hành nào được hỗ trợ. Lệnh cài chỉ là `npx`, nên về lý thuyết chạy được nơi có Node 20 trở lên. Bạn nên thử trên một thư mục dự án nhỏ trước.

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

README nói Claude control mặc định là read + ask, và hành động liên quan mạng, chi tiêu hay phá huỷ luôn cần bạn xác nhận. Mặt khác, các mod chạy với quyền tài khoản của bạn và không được sandbox, nên cần đọc mã trước khi cài. Repo có file SECURITY.md để bạn xem chính sách bảo mật.

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

Claude Code thuần là một agent làm việc đơn lẻ. ruflo thêm lớp harness gồm agent chuyên biệt, swarm, bộ nhớ qua các phiên, hook tự định tuyến và bảng điều khiển. Sau khi `init`, bạn vẫn dùng Claude Code như bình thường.

### Cài bằng plugin và bằng init khác nhau thế nào?

Theo README, đường plugin không thêm file nào vào dự án và không cài hook, chỉ có lệnh slash, vài skill và định nghĩa agent. Đường `npx ruflo init` mang đủ 98 agent, hơn 60 lệnh, 30 skill, MCP server, hook và daemon, nhưng thêm thư mục như `.claude/` và `.claude-flow/` vào dự án. README gợi ý dùng `init` cho việc dùng nghiêm túc.
