# 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: lớp công cụ bọc quanh Claude Code và Codex, thêm đội agent, bộ nhớ dài hạn, 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 từ 20 trở lên. Repo có giấy phép MIT, hiện có khoảng 81.588 sao.

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

ruflo là một "agent harness" mã nguồn mở, viết chủ yếu bằng TypeScript. Nói đơn giản: nó là lớp công cụ đặt quanh Claude Code và Codex, giúp AI không chỉ trả lời từng câu mà còn biết chia việc, nhớ việc và kiểm tra việc. Repo này trước đây có tên Claude Flow, nay đổi tên thành ruflo.

Tác giả giải thích bằng một công thức: Agent = Model + Harness. Model là bộ não viết code. Harness là cái bàn làm việc quanh nó: công cụ, bộ nhớ, vòng lặp, giới hạn an toàn. ruflo chính là phần bàn làm việc đó. Bạn vẫn dùng Claude Code như bình thường, còn ruflo lo phần điều phối phía sau.

Bài này hợp với lập trình viên đã dùng Claude Code hoặc Codex và muốn giao việc lớn hơn cho AI. Bạn làm văn phòng hoặc kinh doanh mà chưa từng mở terminal thì vẫn đọc được. Nhưng bạn nên nhờ người quen code ngồi cùng ở bước cài đặt. Điểm đáng giá nhất là cài chỉ một lệnh, sau đó bạn không cần học hết hàng trăm công cụ bên trong. Repo hiện có khoảng 81.588 sao và 9.608 fork, giấy phép MIT.

```repo
- repo | ruvnet/ruflo
- kind | Framework
- desc | ruflo là bộ khung chạy quanh Claude Code và Codex, thêm agent, bộ nhớ, hook và bảng điều khiển để nhiều agent phối hợp làm việc.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

README nói ruflo có rất nhiều thứ, nhưng người mới chỉ cần nắm vài nhóm chính.

- **Đội agent và swarm.** ruflo thêm hơn 100 agent chuyên biệt, và chúng có thể phối hợp thành "swarm" (đàn agent). Lợi ích thực tế: một việc lớn như rà soát cả repo được chia cho nhiều agent cùng làm, thay vì một cuộc hội thoại dài.
- **Bộ nhớ qua nhiều phiên.** Agent nhớ được những gì đã làm lần trước. Bạn đỡ phải giải thích lại bối cảnh dự án mỗi lần mở Claude Code.
- **Hook tự động.** Sau khi `init`, hook sẽ tự điều hướng tác vụ và học từ những lần làm thành công. README nói rõ bạn cứ dùng Claude Code bình thường, không cần học hết 406 công cụ MCP hay 61 lệnh CLI.
- **Máy chủ MCP.** Codex và các ứng dụng hỗ trợ MCP khác cũng dùng được ruflo qua một lệnh khởi chạy.
- **Bảng điều khiển (console).** Đây là "buồng lái" để theo dõi workflow, agent, model, token và chi phí cạnh Claude Code. Bạn xem được log, tìm kiếm, phát lại và so sánh các lần chạy.
- **Cho Claude điều khiển console có giới hạn.** Trong Settings bạn chọn mức quyền `read`, `write`, `manage` hoặc `full`, và chọn `ask` hoặc `auto` cho việc phê duyệt. Mặc định hiện là read + ask.
- **Hệ plugin.** Có 48 plugin trong marketplace của ruflo: test tự động, quét bảo mật, theo dõi chi phí token, bộ nhớ RAG, tài liệu, v.v.
- **Federation.** Agent trên các máy khác nhau có thể trao đổi với nhau. Bạn mới dùng thì chưa cần đến.

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

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

- **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.
- **Claude Code** nếu bạn đi theo đường chính. Với đường chỉ cài plugin, README yêu cầu Claude Code **2.1.287 trở lên**. Lệnh `claude plugin install` từ terminal cần bản **2.1.292 trở lên**.
- **Một cửa sổ terminal** mở ngay trong thư mục dự án của bạn.
- Nếu dùng Codex hoặc ứng dụng MCP khác: ứng dụng đó phải cho bạn khai báo một máy chủ MCP với lệnh và tham số.

Tư liệu không nói rõ về hệ điều hành, phần cứng hay API key riêng cho ruflo. Cần bao nhiêu RAM, có cần GPU hay không, thì README chưa nói. Bản thân Claude Code hay Codex vẫn cần tài khoản của chúng như bình thường. Muốn biết chi tiết hơn, bạn xem README.md và thư mục docs/ trong repo.

```note
Mod và plugin chạy với quyền tài khoản của bạn và không bị cô lập (sandbox). README khuyên bạn đọc code trước khi cài. Hãy giữ mức quyền Claude control ở read + ask lúc mới dùng.
```

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

```steps
- Mở thư mục dự án | Mở terminal ngay trong thư mục bạn muốn ruflo làm việc
- Chạy init | Một lệnh npx ruflo@latest init thêm agent, hook, bộ nhớ và MCP vào dự án
- Mở lại Claude Code | Mở Claude Code trong cùng thư mục để nó nhận cấu hình mới
- Giao một việc thật | Gõ một yêu cầu cụ thể, nhắc đến swarm của ruflo
- Mở console (tuỳ chọn) | Gõ /ruflo trong Claude Code để xem bảng điều khiển
```

### Mở terminal trong thư mục dự á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 bạn phải đứng đúng thư mục dự án. Trên Windows, bạn có thể mở thư mục trong File Explorer rồi mở PowerShell từ đó. Hoặc dùng `cd`:

```bash
cd đường-dẫn-tới-dự-án-của-bạn
```

Nếu chưa có dự án, bạn tạo một thư mục thử nghiệm rồi `cd` vào. Đừng chạy trong thư mục chứa dữ liệu quan trọng mà bạn chưa sao lưu.

### Chạy lệnh init

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

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

`npx` tải ruflo bản mới nhất rồi chạy. Lệnh `init` thêm agent, hook, bộ nhớ và máy chủ MCP vào dự án. README ghi đường cài này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md` cùng một số file hỗ trợ. Bạn nên xem lại danh sách file thay đổi, nhất là khi dự án đang dùng git.

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
```

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

Mở Claude Code trong cùng thư mục. README nói Claude Code sẽ nhận agent, hook, bộ nhớ và MCP ở lần khởi động kế tiếp. Nếu bạn đang mở sẵn Claude Code, hãy thoát ra rồi mở lại. Sau đó thử 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.
```

### Đường khác: chỉ cài plugin vào Claude Code

Đường này không thêm file nào vào dự án. Nó cài công cụ lõi, console và mod. Bạn gõ các dòng sau ngay trong Claude Code, từng dòng một:

```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 muốn gõ từ terminal (Claude Code 2.1.292 trở lên):

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

README so sánh hai đường như sau: plugin là bản nhẹ, chủ yếu có lệnh gạch chéo và định nghĩa agent, không có hook. Đường `npx ruflo@latest init` là bản đầy đủ gồm 98 agent, hơn 60 lệnh, 30 skill, máy chủ MCP, hook và daemon. README khuyên bản đầy đủ cho dùng thật.

### Đường khác: dùng với Codex hoặc ứng dụng MCP

Trong ứng dụng của bạn, khai báo máy chủ MCP với **command** là `npx` và **arguments** như sau:

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

Cách này tương đương chạy `npx -y ruflo@latest mcp start`. Ứng dụng MCP của bạn đặt ô nhập ở đâu thì README không nói, bạn xem tài liệu của ứng dụng đó.

### Chạy console trong terminal thường

Bảng điều khiển còn chạy riêng được, không cần Claude Code:

```bash
npx ruflo tui
```

Thêm `--plain` nếu muốn in một khung hình ra cho script đọc.

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

Có vài cách để biết cài thành công:

1. **Sau `init`:** terminal không báo lỗi và dự án có thêm các thư mục/file như `.claude/`, `.claude-flow/`, `CLAUDE.md`.
2. **Trong Claude Code:** mở lại, gõ `/ruflo`. Nếu console hiện ra thì ruflo đã nhận. Với đường plugin, gõ `/plugin` để xem ruflo có trong dòng mod đang hoạt động.
3. **Với MCP:** ứng dụng của bạn liệt kê được công cụ của ruflo sau khi khởi động lại.
4. **Thử một việc nhỏ:** giao đúng câu lệnh mẫu ở trên và xem Claude Code có nhắc tới swarm hay agent không.

README lưu ý một điều đáng nhớ: tạo một "mission" trong console không có nghĩa là tính năng đã được code xong. Hãy luôn kiểm tra kết quả thật trong dự án.

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

Dưới đây là vài tình huống bám đúng khả năng README mô tả.

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

Bạn vừa nhận một dự án cũ, chưa ai hiểu rõ. Sau khi `init`, mở Claude Code và gõ câu lệnh mẫu:

```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. Bạn đọc lại phần thay đổi trước khi giữ. Bạn cũng nên chạy test bằng tay một lần.

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

Bạn dẫn một nhóm nhỏ dùng Claude Code và muốn biết agent nào làm gì, tốn bao nhiêu token. Cài đường plugin rồi mở console:

```text
/plugin install ruflo-console@ruflo
/reload-plugins
/ruflo
```

Console cho bạn xem workflow, agent, model, token và chi phí. Bạn mở log của từng agent, tìm lỗi, phát lại và so sánh các lần chạy. README còn có plugin `ruflo-cost-tracker` để đặt ngân sách và nhận cảnh báo chi phí.

> Cứ dùng Claude Code như bình thường, phần điều phối để ruflo lo phía sau.
>
> — Ông T

### Cho Claude tạo một "mission" nhưng vẫn giữ quyền kiểm soát

Đây là bài thử an toàn chính thức trong README. Bạn mở `/ruflo`, vào Settings → Claude control và chọn **write + ask**. Rồi bạn 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ở trang Missions và đặt mục tiêu. Bạn xác nhận hành động tạo trong console. Sau đó kiểm tra: mục Missions có mục tiêu mới, và Overview ghi lại hành động. Nếu muốn dừng, bấm **Take back control**. Các lần gọi tiếp theo sẽ bị từ chối cho đến khi bạn cấp lại quyền.

### Dùng ruflo từ Codex

Bạn dùng Codex thay vì Claude Code. Khai báo máy chủ MCP với `npx` và tham số `["-y", "ruflo@latest", "mcp", "start"]` như phần cài đặt. Sau đó Codex gọi được công cụ ruflo. Mức độ hỗ trợ chi tiết thế nào thì tư liệu tôi có chưa nói rõ, bạn nên thử trên dự án nhỏ trước.

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

**Chạy `init` rồi mà Claude Code không thấy gì.** Thường do bạn chưa mở lại Claude Code, hoặc mở ở thư mục khác. Hãy thoát hẳn, vào đúng thư mục dự án rồi mở lại.

**`npx` báo không tìm thấy hoặc lỗi phiên bản.** `package.json` yêu cầu Node từ 20.0.0 trở lên. Hãy kiểm tra bằng `node --version`. Nếu thấp hơn, cài Node mới hơn rồi chạy lại.

**Lệnh `/plugin install` không nhận hoặc không có.** Đường plugin cần Claude Code 2.1.287 trở lên, và lệnh `claude plugin install` ở terminal cần 2.1.292 trở lên. Hãy cập nhật Claude Code trước. Sau khi cài plugin, gõ `/reload-plugins`.

**Cài cùng một plugin từ hai marketplace.** README cảnh báo một số plugin bên ngoài (như agentic-qe-fleet, agentdb, agentic-flow) chỉ nên cài từ một marketplace. Nếu bật từ cả hai nơi, mod và lệnh sẽ nạp hai lần. Hãy gỡ bớt một bên.

**Claude hỏi quyền liên tục hoặc bị từ chối hành động.** Đây là thiết kế an toàn. Mặc định là read + ask, và các hành động vượt mức quyền sẽ bị từ chối. Việc dùng mạng, tiêu tiền hoặc xoá dữ liệu luôn cần bạn xác nhận, kể cả khi chọn auto. Chỉ nâng mức quyền khi bạn đã hiểu hành động đó làm gì.

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

**Điểm mạnh.**
- Cài nhanh, chỉ một lệnh, giấy phép MIT.
- Có nhiều đường vào: đầy đủ, chỉ plugin, MCP, terminal.
- Có console để quan sát và giới hạn quyền. Mặc định là read + ask, nên khá thận trọng.
- Repo còn được cập nhật trong 3 tháng gần đây.

**Giới hạn.**
- Hệ thống rất lớn: 98 agent, hàng trăm công cụ MCP, 48 plugin. Người mới dễ bị ngợp.
- `init` thêm khá nhiều file vào dự án. Hãy dùng git để xem và hoàn tác thay đổi.
- README tự nói vài phần chỉ là mô tả khái niệm, và một số demo dùng dữ liệu mẫu, không chứng minh swarm đã làm xong việc thật. Bạn nên tự kiểm tra kết quả.
- Tài liệu tôi có không nêu rõ chi phí chạy hay yêu cầu phần cứng. Việc dùng Claude Code hoặc Codex vẫn tốn quota hoặc tiền theo tài khoản của bạn.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần Claude Code trả lời và sửa code cho một việc nhỏ, dùng Claude Code thuần cho gọn. ruflo đáng thử khi việc đủ lớn để chia cho nhiều agent, hoặc khi bạn muốn bộ nhớ qua nhiều phiên và một bảng điều khiển theo dõi. Hãy bắt đầu trên một dự án thử, không phải dự án sản xuấ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. Tuy vậy bạn vẫn dùng Claude Code hoặc Codex theo gói của chính chúng. Tư liệu chưa nêu chi phí cụ thể khi chạy nhiều agent.

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

Mở terminal trong thư mục dự án rồi chạy `npx ruflo@latest init`. Sau đó mở lại Claude Code trong cùng thư mục. Ngoài ra có đường chỉ cài plugin hoặc đường dùng MCP cho Codex.

### Cần phiên bản Node nào?

`package.json` yêu cầu Node từ 20.0.0 trở lên. Đường cài plugin còn cần Claude Code từ 2.1.287, và lệnh `claude plugin install` ở terminal cần từ 2.1.292.

### Có cần GPU không, chạy Windows được không?

Tư liệu tôi có không nói rõ về GPU hay hệ điều hành. Vì cài qua `npx` trên Node, nhiều khả năng chạy được trên các máy có Node, nhưng chưa có xác nhận chính thức. Bạn nên xem README và thư mục docs trong repo.

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

ruflo là lớp bọc quanh Claude Code, thêm đội agent, swarm, bộ nhớ qua nhiều phiên, hook và console theo dõi. Bạn vẫn dùng Claude Code như thường, còn ruflo điều phối phía sau.

### Dùng ruflo có an toàn không?

Phần Claude control mặc định là read + ask, và hành động dùng mạng, tiêu tiền hoặc xoá luôn cần bạn xác nhận. Nhưng mod và plugin chạy với quyền tài khoản của bạn và không bị sandbox, nên README khuyên đọc code trước khi cài.

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

Có. README nói Codex và các ứng dụng MCP khác dùng được bằng cách khai báo lệnh `npx` với tham số `-y ruflo@latest mcp start`. README cũng nhắc tới một số công cụ khác như Grok Build. Mức hỗ trợ chi tiết thì tư liệu chưa nói rõ.
