Ruflo

1. Ruflo là gì? (Ruflo GitHub dùng để làm gì)

Ruflo là một công cụ dành cho lập trình viên. Nó không phải app chat, không có cửa sổ để bấm, và tự nó không viết được dòng code nào. Ruflo là lớp phụ trợ gắn thêm vào Claude Code hoặc Codex (hai trợ lý lập trình AI chạy trong cửa sổ dòng lệnh) để các trợ lý này làm việc theo nhóm.

Tác giả mô tả ý tưởng như sau: mô hình AI lo phần viết, còn "harness" (bộ khung bao quanh mô hình) lo cấp công cụ, bộ nhớ và cách điều phối. Ruflo là bộ khung đó. Khi cài bản đầy đủ, nó thêm khoảng 100 agent chuyên việc (README chỗ ghi "100+", chỗ ghi 98) (agent là một "nhân viên AI" đảm nhận một vai như viết code, kiểm thử, rà bảo mật), cho các agent phối hợp thành nhóm, và lưu lại bộ nhớ giữa các phiên làm việc. Trước đây dự án có tên Claude Flow, nên bạn sẽ còn gặp tên claude-flow trong một số lệnh và thư mục.

Ruflo là mã nguồn mở, giấy phép MIT, không thu phí. Nhưng nó cần một trợ lý lập trình đứng bên dưới, và trợ lý đó thường tính tiền.

Hợp với bạn nếu:

• Bạn đã dùng Claude Code hoặc Codex để viết phần mềm.
• Bạn làm dự án đủ lớn để cần chia việc cho nhiều agent cùng lúc.
• Bạn quen gõ lệnh và đọc được thông báo bằng tiếng Anh.

Chưa hợp nếu:

• Bạn chưa từng lập trình. Ruflo không giúp bạn làm được gì nếu không có dự án phần mềm để nó làm việc.
• Bạn tìm một chatbot miễn phí. Ruflo không kèm mô hình AI nào.
• Bạn mới cài Claude Code hôm qua. Hãy dùng thuần Claude Code một thời gian rồi mới thêm Ruflo.

2. Cần chuẩn bị gì?

• Máy tính Windows, macOS hoặc Linux. Ruflo không chạy trên điện thoại.
• Node.js 20 trở lên, kèm npm 9 trở lên. Node.js là phần mềm để chạy các công cụ viết bằng JavaScript; npm là trình cài gói đi kèm Node.js. Tải tại https://nodejs.org
• Claude Code đã cài và đã đăng nhập. Tài liệu Ruflo ghi rõ phải cài Claude Code trước. Claude Code là sản phẩm của Anthropic và cần gói thuê bao hoặc khóa API trả tiền; xem điều kiện tại https://docs.anthropic.com/en/docs/claude-code
• Git, công cụ quản lý mã nguồn. Lệnh kiểm tra sức khỏe của Ruflo có kiểm tra Git. Tải tại https://git-scm.com/downloads
• Dung lượng: bản cài đầy đủ khoảng 340 MB; bản rút gọn khoảng 45 MB.
• Một thư mục dự án để thử. Tác giả khuyên dùng một dự án nhỏ, không chứa mật khẩu hay khóa bí mật.

Bản Ruflo mới nhất lúc viết bài là v3.48.0, phát hành ngày 28/9/2026.

3. Cách cài Ruflo từng bước

Ruflo có hai đường cài rất khác nhau. Chọn một đường thôi; tài liệu của tác giả cảnh báo rằng cài cả hai bản cùng lúc làm trợ lý bối rối khi tìm công cụ.

	Đường A: plugin trong Claude Code	Đường B: cài bằng dòng lệnh
Bạn nhận được	Các lệnh gạch chéo, vài skill và định nghĩa agent	Toàn bộ Ruflo: agent, lệnh, skill, máy chủ MCP, hook
File thêm vào dự án	Không có	.claude/, .claude-flow/, CLAUDE.md và vài file phụ
Nên chọn khi	Muốn thử nhẹ, không đụng vào dự án	Dùng thật, muốn đủ tính năng như tài liệu

Bước 1: Kiểm tra Node.js

node --version
npm --version

Đúng là khi: số đầu in ra từ v20 trở lên, số sau từ 9 trở lên. Nếu máy báo không tìm thấy lệnh hoặc số nhỏ hơn, cài bản mới từ https://nodejs.org rồi mở lại cửa sổ dòng lệnh.

Bước 2: Cài Claude Code (nếu chưa có)

npm install -g @anthropic-ai/claude-code

Sau đó gõ claude để mở và đăng nhập theo hướng dẫn trên màn hình.

Đúng là khi: gõ claude thì vào được giao diện của Claude Code.

Bước 3 (Đường A): Cài plugin bên trong Claude Code

Hai lệnh dưới đây gõ bên trong Claude Code, không phải ở dòng lệnh thường:

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo

Bắt đầu với ruflo-core là đủ. Khi có nhu cầu cụ thể mới thêm plugin khác, ví dụ ruflo-swarm để điều phối nhóm agent:

/plugin install ruflo-swarm@ruflo

Đúng là khi: Claude Code báo plugin đã được cài và bạn thấy các lệnh mới của Ruflo khi gõ dấu /.

Bước 3 (Đường B): Cài đầy đủ bằng dòng lệnh

Trước hết dùng lệnh cd để vào thư mục dự án của bạn. Sau đó chạy lệnh dưới đây; nó hoạt động giống nhau trên Windows (PowerShell hoặc cmd), macOS và Linux:

npx ruflo@latest init wizard

Trình hướng dẫn sẽ hỏi bạn vài câu rồi tạo cấu hình. Nếu không muốn trả lời câu hỏi, dùng bản chạy nhanh:

npx ruflo@latest init

Trên macOS, Linux hoặc WSL còn có lệnh cài một dòng:

curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

Đúng là khi: trong thư mục dự án xuất hiện thư mục .claude/, thư mục .claude-flow/ và file CLAUDE.md.

Lưu ý: Nếu dự án của bạn đã có sẵn .claude/ hoặc CLAUDE.md, hãy sao lưu trước khi chạy init.

Bước 4: Kiểm tra sức khỏe

npx ruflo@latest doctor

Lệnh này kiểm tra phiên bản Node.js, npm, Git, file cấu hình, bộ nhớ, máy chủ MCP và dung lượng đĩa.

Đúng là khi: bạn thấy danh sách các mục kiểm tra và một dòng tổng kết số mục đạt. Mục nào tự sửa được thì chạy thêm:

npx ruflo@latest doctor --fix

4. Dùng lần đầu

Điều đáng biết nhất: sau khi init, bạn dùng Claude Code như bình thường. README ghi rõ bạn không cần học hết hàng trăm công cụ và hàng chục lệnh; hệ thống hook tự phân việc và điều phối agent ở phía sau.

Thử một việc an toàn theo gợi ý của tác giả, tức là bắt đầu bằng việc xem, chưa sửa gì:

1. Mở cửa sổ dòng lệnh trong thư mục dự án và gõ claude.
2. Dán yêu cầu sau (bằng tiếng Anh hoặc tiếng Việt đều được):

Hãy xem qua dự án này, dùng Ruflo ở chỗ nào có ích. Trước hết tóm tắt mục đích của dự án và cách chạy test. Đề xuất ba việc rà soát độc lập. Lượt đầu chỉ đọc: không cài gì, không sửa file, không commit, không triển khai. Trả kết quả kèm tên file liên quan và những điểm bạn chưa chắc.

3. Đọc bản kế hoạch trợ lý đưa ra. Thấy ổn thì mới cho phép làm một thay đổi cụ thể, kèm điều kiện dừng rõ ràng.

Kết quả trông thế nào: trợ lý trả về phần tóm tắt dự án và danh sách việc đề xuất, không có file nào bị thay đổi.

Muốn xem Ruflo có những loại agent nào:

npx ruflo@latest agent list

Tác giả có một bài hướng dẫn 14 chương cho người mới, đọc tại https://github.com/ruvnet/ruflo/blob/main/docs/ruflo-explained.md

5. Lỗi thường gặp khi cài Ruflo và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Windows báo 'bash' is not recognized	Lệnh cài một dòng curl ... | bash cần môi trường kiểu Linux	Dùng npx ruflo@latest init wizard. Hai cách chạy cùng một quy trình cài
npx hoặc node báo "command not found" / "not recognized"	Chưa cài Node.js hoặc cửa sổ dòng lệnh chưa nhận	Cài Node.js từ https://nodejs.org, đóng và mở lại cửa sổ dòng lệnh
doctor báo Node.js không đạt	Node.js cũ hơn bản 20	Nâng cấp Node.js bằng tay. Đây là mục doctor không tự sửa được
Lỗi "permission denied" khi cài trên macOS / Linux	Thư mục lưu tạm của npm thuộc quyền tài khoản khác	Chạy lệnh sửa quyền bên dưới bảng
Máy chủ MCP không khởi động	Cổng đang bị một tiến trình khác chiếm	Tìm và tắt tiến trình đó, rồi chạy npx ruflo@latest mcp start. Lệnh mẫu có trong mục Troubleshooting của User Guide
Tạo agent thất bại trên máy ít RAM	Quá nhiều agent chạy cùng lúc	Giảm số agent tối đa bằng biến môi trường bên dưới bảng
Trợ lý thấy công cụ Ruflo bị trùng	Bạn cài cả plugin lẫn đăng ký MCP trực tiếp	Giữ một đường kết nối, gỡ đường còn lại

Sửa quyền npm (macOS / Linux):

sudo chown -R $(whoami) ~/.npm

Giảm số agent tối đa (macOS / Linux):

export CLAUDE_FLOW_MAX_AGENTS=5

Chưa hết lỗi? Xem User Guide tại https://github.com/ruvnet/ruflo/blob/main/docs/USERGUIDE.md hoặc hỏi ở kênh Issues được README dẫn tới: https://github.com/ruvnet/claude-flow/issues

6. Gỡ cài đặt / cập nhật

Cập nhật (Đường B): chạy trong thư mục dự án.

npx ruflo@latest init upgrade

Lệnh này cập nhật các file phụ trợ và giữ nguyên dữ liệu của bạn. Muốn thêm cả các skill, agent, lệnh mới có ở bản sau:

npx ruflo@latest init upgrade --add-missing

Gỡ (Đường B):

1. Trong thư mục dự án, xóa những thứ init đã tạo: thư mục .claude-flow/, và thư mục .claude/ cùng file CLAUDE.md nếu chúng do Ruflo sinh ra. Nếu bạn đã có các file này từ trước, chỉ khôi phục bản sao lưu.
2. Nếu bạn đã cài Ruflo toàn cục bằng npm install -g ruflo@latest, gỡ bằng:

npm uninstall -g ruflo

3. Nếu bạn đã đăng ký máy chủ MCP bằng lệnh claude mcp add claude-flow ..., gỡ bằng:

claude mcp remove claude-flow

Gỡ (Đường A): mở Claude Code, gõ /plugin và gỡ các plugin có tên bắt đầu bằng ruflo- trong trình quản lý plugin. Đường này không để lại file nào trong dự án.

7. Câu hỏi hay gặp

Có mất tiền không? Ruflo miễn phí, giấy phép MIT. Khoản mất tiền là trợ lý và mô hình AI bên dưới. Tác giả cũng lưu ý: chạy nhiều agent song song có thể rút ngắn thời gian chờ nhưng làm tăng lượng token tiêu thụ, tức là có thể tốn hơn chứ không rẻ hơn.

Có cần mạng không? Có. Cần mạng để tải gói qua npx và để trợ lý gọi tới mô hình AI. Tài liệu có nhắc tới việc chạy mô hình cục bộ qua Ollama bằng một plugin riêng, nhưng đó là cấu hình nâng cao.

Dữ liệu của tôi có bị gửi đi đâu không? Các file cấu hình Ruflo tạo ra nằm trong thư mục dự án, và bộ nhớ của nó là một cơ sở dữ liệu lưu trên máy bạn. Tuy vậy, như mọi trợ lý lập trình AI, nội dung bạn yêu cầu xử lý vẫn được gửi tới nhà cung cấp mô hình mà bạn dùng. Tính năng liên kết agent giữa nhiều máy (federation) là tùy chọn, phải tự bật.

Không biết lập trình có dùng được không? Không nên. Ruflo chỉ có ích khi bạn có một dự án phần mềm và đủ khả năng đọc, duyệt các thay đổi mà agent đề xuất.

Dùng với Codex thay vì Claude Code được không? Được. Ruflo có lệnh khởi tạo riêng cho Codex là npx ruflo@latest init --codex. Chi tiết xem User Guide.