# 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), bọc quanh Claude Code và Codex để thêm agent chuyên biệt, hook, bộ nhớ và MCP server. Bạn chạy một lệnh `npx ruflo@latest init` trong thư mục dự án rồi dùng Claude Code như bình thường. Cài đặt khá đơn giản nếu đã có Node 20 trở lên, nhưng bộ công cụ rất lớn nên nên bắt đầu từ việc nhỏ.

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

Ruflo là một “agent harness” mã nguồn mở: lớp công cụ bao quanh Claude Code và Codex, giúp các AI agent có thêm bộ nhớ, hook, MCP server và khả năng phối hợp thành nhóm (swarm). Tác giả mô tả ngắn gọn: mô hình AI là bộ não viết code, còn harness là cái bàn làm việc đầy đủ dụng cụ để bộ não đó làm việc thật. Ruflo chính là cái bàn làm việc đó.

Bạn nên xem repo này nếu đã dùng Claude Code hoặc Codex và thấy một agent đơn lẻ chưa đủ: quên ngữ cảnh giữa các phiên, không biết chia việc, khó theo dõi chi phí. Ruflo thêm hơn 100 agent chuyên biệt, bộ nhớ lưu qua nhiều phiên và một giao diện “buồng lái” để xem agent đang làm gì.

Điểm đáng giá nhất là cách cài rất ngắn. README nói bạn không cần học hết hàng trăm công cụ MCP hay lệnh CLI. Sau khi `init`, bạn cứ dùng Claude Code như thường, phần hook sẽ tự định tuyến tác vụ và phối hợp agent ở phía sau. Repo hiện có khoảng 81.600 sao và 9.600 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

```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ớ dài hạn, swarm phối hợp và MCP server chỉ với một lệnh init.
- stars | 82k
- lang | TypeScript
- license | MIT
```

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

Dưới đây là những nhóm tính năng chính, giải thích theo lợi ích thực tế.

### Thêm agent và swarm cho Claude Code

Sau `init`, dự án của bạn có thêm các agent chuyên biệt, lệnh và skill. README ghi con số khoảng 98 agent, hơn 60 lệnh và 30 skill cho đường cài bằng CLI. Lợi ích: bạn có thể nhờ Claude Code xử lý một việc lớn bằng cách chia cho nhiều agent, thay vì một agent làm tất cả.

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

Ruflo có bộ nhớ tự học, lưu kinh nghiệm từ các tác vụ đã làm và dùng lại cho lần sau. Các plugin như `ruflo-agentdb` (cơ sở dữ liệu vector cho bộ nhớ agent), `ruflo-rag-memory` (tìm kiếm thông minh) và `ruflo-rvf` (lưu và khôi phục bộ nhớ giữa các phiên) phục vụ phần này. Lợi ích: bớt phải giải thích lại dự án mỗi lần mở phiên mới.

### Buồng lái (console) ngay cạnh Claude Code

Plugin `ruflo-console` cho bạn theo dõi quy trình, agent, mô hình, token và chi phí. Bạn có thể mở log của agent, tìm kiếm, phân loại lỗi, phát lại và so sánh các lần chạy. Lệnh mở giao diện là `/ruflo` trong Claude Code.

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

Trong Settings có mục “Claude control”. Bạn chọn mức quyền `read`, `write`, `manage` hoặc `full`, và chế độ duyệt `ask` hoặc `auto`. Mặc định hiện là read + ask. README nói các hành động liên quan mạng, chi tiêu và phá hủy vẫn cần xác nhận ngay cả khi ở `auto`, và có nút “Take back control” để thu hồi quyền.

### Hệ sinh thái plugin

README liệt kê 48 plugin (cộng thêm 3 plugin bên ngoài), chia theo nhóm: điều phối, bộ nhớ, học máy, kiểm thử, bảo mật, DevOps, mở rộng. Ví dụ: `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 và đặt ngân sách, `ruflo-docs` tạo và duy trì tài liệu.

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

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

## 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 như vậy. 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 ghi cần 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 thư mục dự án** để chạy `init`. Lệnh này ghi file vào thư mục đó.

README không nêu yêu cầu về hệ điều hành hay phần cứng cụ thể (như GPU), và không nói rõ cần API key nào để chạy cơ bản. Một số tính năng như học máy hay embeddings cần module cấu hình riêng; chi tiết xem thêm trong thư mục `docs/` của repo.

```note
Mod và plugin của Ruflo chạy với quyền tài khoản của bạn và không nằm trong sandbox. README khuyên đọc code của chúng trước khi cài. Hãy thử trong một dự án nháp trước khi đụng vào dự án thật.
```

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

README có ba đường cài. Mình hướng dẫn đường chính (CLI `init`) trước, rồi hai đường phụ.

```steps
- Mở terminal đúng thư mục | Vào thư mục dự án mà bạn muốn thêm Ruflo
- Chạy init | Dùng npx để thêm agent, hook, bộ nhớ và MCP server vào dự án
- Khởi động 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õ yêu cầu dùng swarm của Ruflo
- Mở buồng lái | Gõ /ruflo trong Claude Code để xem console
```

### Mở terminal ở 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. Nếu chưa có dự án, hãy tạo một thư mục nháp để thử. Ví dụ trên Windows, bạn mở PowerShell rồi dùng `cd` để vào thư mục:

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

### Chạy lệnh init

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

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

`npx` tải và chạy gói `ruflo` bản mới nhất mà không cần cài toàn cục. `init` thêm agent, hook, bộ nhớ và MCP server vào dự án. README cho biết đường này tạo các thư mục và file như `.claude/`, `.claude-flow/`, `CLAUDE.md`, file hỗ trợ và settings trong dự án của bạn. Nếu bạn đã có `CLAUDE.md` riêng, hãy sao lưu trước.

Nếu muốn thiết lập theo kiểu hỏi đáp, README có lệnh:

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

Nếu muốn xem trước, README có nói về cờ `--dry-run` cho phiên bản `--grok`:

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

Lệnh trên dành riêng cho Grok Build, ghi bề mặt dự án (`.grok/`, team bus và hướng dẫn vận hành) và không ghi gì ngoài dự án. Bạn thêm `--dry-run` để xem trước.

### Khởi động 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 Claude Code, hãy thoát và mở lại.

### Đường phụ 1: chỉ cài plugin Claude Code (không thêm file vào dự án)

Đường này cài công cụ lõi, buồng lái và mod, không thêm file nào vào dự án. Chạy bên trong Claude Code:

```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ừng dòng làm gì: dòng đầu thêm “chợ” plugin của Ruflo; ba dòng `install` cài từng plugin; `/reload-plugins` nạp lại; `/ruflo` mở buồng lái. Từ terminal thường, trên Claude Code 2.1.292 trở lên, bạn có thể dùng:

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

README cũng ghi `ruflo-swarm` (hiện swarm trong một pane) và `ruflo-ruos` (thêm đoạn trạng thái ruOS) là các plugin tùy chọn.

### Đường phụ 2: Codex hoặc client MCP khác

Bạn cấu hình **command** là `npx` và **arguments** là:

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

Cách điền vào client cụ thể (Codex, v.v.) tùy giao diện của từng client; README chưa kèm ví dụ file cấu hình, nên bạn xem thêm tài liệu của client đó.

### Đường phụ 3: chạy console trong terminal thường

Console chạy độc lập, không cần Claude Code:

```bash
npx ruflo tui
```

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

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

Với đường `init`, README mô tả các dấu hiệu sau:

- Trong thư mục dự án xuất hiện các mục như `.claude/`, `.claude-flow/` và `CLAUDE.md`.
- Sau khi khởi động lại Claude Code, gõ `/ruflo` sẽ mở buồng lái.
- Giao một tác vụ thật cho Claude Code (xem phần dưới) và xem agent được điều phối.

Với đường chỉ cài plugin, README nói bạn mở `/plugin` và kiểm tra các mod xuất hiện trong dòng “active mods”. Trong console, lệnh `/ruflo market` mở danh mục plugin, nơi bạn cài, bật, tắt và cập nhật (mỗi hành động đều hỏi lại bạn trước).

Với đường Codex/MCP, README chưa nêu cách kiểm tra riêng. Bạn có thể xem client của mình có liệt kê được các công cụ MCP của ruflo hay không.

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

Các tình huống dưới đây bám đúng khả năng được README mô tả. Kết quả thực tế sẽ tùy dự án và mô hình bạn dùng.

### Dev mới nhận một dự án lạ: nhờ swarm rà soát

Bạn vừa nhận một repo chưa quen. Sau khi `init` và mở lại Claude Code, bạn dán đú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.
```

Câu này yêu cầu swarm tìm module rủi ro nhất, viết test cho nó rồi tóm tắt thay đổi. Bạn nhận lại một bản tóm tắt và các file test mới để tự xem lại. Hãy đọc diff trước khi giữ lại.

> Agent = Mô hình + Harness: mô hình viết code, còn harness cho nó công cụ, bộ nhớ và giới hạn để làm việc thật.
>
> — Ông T

### Chủ dự án muốn nhìn rõ agent đang làm gì và tốn bao nhiêu

Bạn chạy một loạt tác vụ và muốn biết agent nào làm gì. Cài `ruflo-console`, mở `/ruflo` để theo dõi quy trình, token và chi phí; mở log để tìm tác vụ lỗi và phát lại. Nếu muốn có cảnh báo chi tiêu, README có plugin `ruflo-cost-tracker` (theo dõi token, đặt ngân sách, cảnh báo chi phí). Kết quả: bạn thấy bức tranh toàn cảnh thay vì đoán mò.

### Thử cho Claude điều khiển console với quyền hạn chế

Đây là bài tập an toàn mà README mô tả từng bước:

1. Mở `/ruflo`, vào Settings → Claude control, chọn **write + ask**.
2. Gõ yêu cầu: “Create a mission to add a dark mode toggle. Show me the mission and its status.”
3. Claude mở mục Missions và đặt mục tiêu. Bạn xác nhận hành động tạo đang chờ.
4. Kiểm tra mục Missions có mục tiêu đó và mục Overview có ghi lại hành động.

Lưu ý README nhấn mạnh: tạo mission không có nghĩa là tính năng đã được viết xong. Nếu muốn dừng, bấm “Take back control”.

### Dùng Ruflo như MCP server cho Codex

Nếu bạn dùng Codex hơn Claude Code, cấu hình MCP với command `npx` và arguments như ở phần cài đặt. Khi đó công cụ của Ruflo có sẵn trong client MCP của bạn mà không cần thêm file vào dự án. Kết quả cụ thể phụ thuộc vào client; README chưa có ví dụ chi tiết cho Codex.

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

Một số lỗi dưới đây là suy ra từ cách hoạt động của loại công cụ này; chưa phải mọi lỗi đều có trong README.

### Gõ `/ruflo` mà không thấy gì

Thường do Claude Code chưa nạp cấu hình. Hãy thoát và mở lại Claude Code trong đúng thư mục đã chạy `init`. Với đường plugin, chạy `/reload-plugins`, rồi mở `/plugin` xem plugin đã nằm trong danh sách chưa.

### Lệnh `/plugin install` báo lỗi hoặc không có lệnh

README ghi đường plugin cần Claude Code từ **2.1.287** trở lên, và lệnh `claude plugin install` ở terminal cần từ **2.1.292**. Hãy kiểm tra phiên bản Claude Code và cập nhật nếu đang dùng bản cũ.

### `npx` không chạy được hoặc báo thiếu phiên bản

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

### Cài một plugin hai lần từ hai nơi

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

### Hai kiểu cài trộn lẫn gây nhầm tên công cụ

README giải thích tên công cụ MCP khác nhau giữa đường plugin (dạng `mcp__plugin_ruflo-core_ruflo__memory_store`) và đường CLI (tên trần như `memory_store`). Nếu bạn làm theo tài liệu của đường này mà đang dùng đường kia, công cụ sẽ “không tìm thấy”. Hãy chọn một đường và bám theo nó.

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

**Điểm mạnh.** Cài đặt ngắn gọn chỉ với một lệnh; có sẵn nhiều agent, skill và plugin; có buồng lái để theo dõi; có cơ chế giới hạn quyền khi cho Claude điều khiển console; giấy phép MIT; dự án đang được cập nhật và có cộng đồng lớn.

**Giới hạn.** Bộ công cụ rất lớn nên người mới dễ choáng; đường `init` thêm khá nhiều file vào dự án; mod chạy với quyền tài khoản và không có sandbox. README cũng thẳng thắn rằng các video minh họa 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ớ nhớ lại được. Phần học và truy xuất cục bộ vẫn cần embeddings và các module cấu hình đi kèm.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần Claude Code làm các việc nhỏ lẻ, một mình nó là đủ, chưa cần thêm lớp điều phối. Nếu bạn chưa quen terminal, hãy thử đường plugin trước để không thêm file vào dự án. Nếu bạn làm việc với dữ liệu nhạy cảm, hãy đọc kỹ `SECURITY.md` và code của plugin trước khi cho chạy.

Lời khuyên của mình: thử trong một thư mục nháp, giao một việc nhỏ như ví dụ rà soát repo, xem kết quả rồi mới quyết định đưa vào 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 miễn phí. Tuy nhiên, các mô hình AI phía sau (như Claude hay Codex) có thể tính phí theo tài khoản của bạn. README có plugin `ruflo-cost-tracker` để theo dõi token và đặt ngân sách.

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

Tư liệu không nói Ruflo bắt buộc phải có GPU. Một plugin phụ là `ruflo-ruvector` được mô tả là có tìm kiếm tăng tốc GPU, nhưng đó là tùy chọn. Yêu cầu phần cứng chi tiết chưa có thông tin.

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

README không nêu rõ hệ điều hành được hỗ trợ. Yêu cầu được ghi là Node 20.0.0 trở lên và lệnh `npx`. Bạn nên thử trong thư mục nháp trước, và xem thư mục `docs/` của repo nếu gặp vấn đề riêng của Windows.

### Ruflo khác gì so với dùng Claude Code trực tiếp?

Claude Code là công cụ chính để viết code; Ruflo là lớp bao quanh nó. Ruflo thêm agent chuyên biệt, swarm, bộ nhớ qua nhiều phiên, hook và buồng lái để theo dõi. Sau `init`, bạn vẫn dùng Claude Code như bình thường.

### Dữ liệu của tôi có an toàn không?

README nói mod và plugin chạy với quyền tài khoản của bạn và không nằm trong sandbox, nên cần đọc code trước khi cài. Với tính năng Claude control, mặc định là read + ask, và các hành động liên quan mạng, chi tiêu, phá hủy luôn cần xác nhận. Repo có file SECURITY.md để bạn đọc thêm.

### Có 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 là `npx` với arguments `["-y", "ruflo@latest", "mcp", "start"]`. Ngoài ra có tùy chọn `npx ruflo init --grok` cho Grok Build.

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

Đường `npx ruflo@latest init` thêm file vào dự án, như `.claude/`, `.claude-flow/` và `CLAUDE.md`. Đường chỉ cài plugin Claude Code thì README ghi là không thêm file nào vào dự án. Bạn nên chọn đường phù hợp mức độ bạn muốn thay đổi.
