openrig: xây đội agent AI bền vững — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
OpenRig là CLI mã nguồn mở để xây dựng và vận hành mạng lưới agent AI từ Claude Code, Codex và Pi. Công cụ phù hợp khi bạn muốn nhiều agent phối hợp lâu dài trong một repository; cài đặt cần Node.js 22 hoặc 24, tmux và macOS, Linux hoặc WSL2.
OpenRig là CLI giúp bạn biến nhiều phiên làm việc của Claude Code, Codex và Pi thành một đội agent có tổ chức. Bạn định nghĩa đội bằng YAML, khởi động bằng một lệnh, rồi giao mục tiêu cho agent điều phối để họ phân chia việc cho các chuyên gia.
Điểm đáng giá nhất là OpenRig giữ đội agent, vai trò, ngữ cảnh và công việc ở những địa chỉ ổn định. Thay vì mỗi lần mở vài cửa sổ terminal rồi tự nhớ agent nào đang làm gì, bạn có thể dùng một kernel operator, các team dựng sẵn và giao việc theo từng mục tiêu cụ thể.
Công cụ này hợp với lập trình viên, nhóm phát triển sản phẩm, người đang thử nghiệm quy trình nhiều agent và người muốn giao một thay đổi có giới hạn cho AI rồi yêu cầu kiểm tra lại. Nếu bạn chỉ cần hỏi đáp với một chatbot hoặc sửa nhanh một file, OpenRig có thể nhiều hơn nhu cầu.
mvschwarz/openrig
OpenRig biến Claude Code, Codex và Pi thành một đội agent có vai trò, bộ nhớ chung và công việc riêng.
I.OpenRig làm được gì
A.Biến nhiều coding agent thành một đội
OpenRig có thể quản lý Claude Code và Codex trong cùng một rig. Một rig là nhóm agent có vai trò, phạm vi công việc và cách phối hợp riêng. Bạn nói kết quả mong muốn với agent dẫn dắt, còn đội tự điều phối các bước chuyên môn.
Cách này hữu ích khi một thay đổi cần người xây dựng, người kiểm tra chất lượng, người tư vấn hoặc nhiều reviewer độc lập. Bạn vẫn nhận kết quả và quyết định cần chú ý thay vì phải tự chuyển tiếp từng mẩu việc.
B.Giữ ngữ cảnh và công việc lâu dài
OpenRig được thiết kế cho các team persistent. Các agent có thể tiếp tục làm việc trong cùng repository, dùng ngữ cảnh chung và theo dõi công việc qua queue. Điều này phù hợp với dự án phát triển liên tục, nơi một nhiệm vụ không nhất thiết hoàn tất trong một phiên terminal.
Bạn cũng có thể yêu cầu agent ghi ID của task, liệt kê queue và trả về cách thử kết quả. Nhờ vậy, quá trình làm việc dễ kiểm tra hơn một cuộc trò chuyện đơn lẻ.
C.Dùng team dựng sẵn hoặc tự xây team
OpenRig cung cấp các team như starter, workshop và factory. starter dành cho một thay đổi có giới hạn, với builder và reviewer. workshop có lead, builder, QA và reviewer cho công việc đang diễn ra trong một repository. factory có bảy agent cho công việc sản phẩm dài hơi.
Bạn có thể bắt đầu bằng team dựng sẵn, sau đó học cách đặt tên pod, vai trò và tạo team riêng. Team starter có thể được điều chỉnh để chạy với chỉ Claude Code hoặc chỉ Codex.
D.Điều phối qua terminal và giao diện TUI
OpenRig có daemon, dashboard và operator. Lệnh rig tui mở dashboard của team. Lệnh mở terminal đã lưu giúp bạn quay lại kernel operator hoặc xem các agent đang chạy.
OpenRig dùng Herdr khi có cài đặt, nếu không thì dùng bố cục tmux tương tự. Bạn có thể làm việc trong terminal nhìn thấy được, cửa sổ tmux hoặc tab terminal tùy môi trường.
E.Theo dõi trạng thái và gửi việc có kiểm soát
Bạn có thể kiểm tra các seat bằng rig ps --nodes --rig starter, gửi một mục tiêu cụ thể bằng rig send và xem queue bằng rig queue list. README khuyến nghị giao một kết quả có phạm vi rõ ràng, yêu cầu builder ghi task, kiểm tra hành vi và nhờ reviewer xem đúng candidate đó.
Quy trình này giúp tránh việc giao một yêu cầu quá rộng rồi không biết agent đã làm đến đâu. Nó cũng tạo ra điểm kiểm tra trước khi bạn nhận thay đổi vào dự án.
F.Tích hợp vào coding agent hiện có
Bạn có thể cài skill rigs vào Claude Code hoặc Codex bằng npx skills add. Sau đó, dùng /rigs trong Claude Code hoặc $rigs trong Codex để agent hướng dẫn cài OpenRig, mở giao diện và chuyển mục tiêu cho operator.
Cách này phù hợp với người mới vì coding agent sẽ nói trước những gì nó chuẩn bị chạy và thay đổi. Tuy nhiên, bạn vẫn cần đọc kỹ quyền truy cập mà setup sẽ thêm vào máy.
II.Cần chuẩn bị gì
OpenRig yêu cầu Node.js phiên bản 22 hoặc 24. Trên máy Mac dùng Apple silicon, README khuyến nghị Node.js 22. npx đi kèm Node.js và được dùng trong cách cài qua skill.
Bạn cần tmux và hệ điều hành macOS hoặc Linux. Windows native chưa được hỗ trợ; nếu dùng Windows, hãy chạy OpenRig trong WSL2. README nói các bài kiểm thử tự động của OpenRig hiện chưa chạy trên WSL2.
Bạn cần ít nhất một tài khoản Claude Code hoặc Codex đã đăng nhập. Chỉ một provider là đủ để bắt đầu; không cần đăng ký thêm provider thứ hai. Team starter mặc định dùng cả Claude Code và Codex nhưng operator có thể điều chỉnh team cho provider bạn đang có.
Trên Linux, Node.js do hệ điều hành cung cấp có thể quá cũ, vì vậy README nêu cách dùng nvm hoặc NodeSource để cài phiên bản được hỗ trợ. Trên macOS, việc cài Node.js bằng nvm có thể cần Apple Command Line Tools nếu hệ thống yêu cầu.
OpenRig có thể cài Herdr và chỉnh một số thiết lập của coding agent, tmux, workspace và project. Hãy sao lưu các file cấu hình quan trọng trước khi chạy setup.
OpenRig có thể tạo hook thực thi, thay đổi thiết lập tin cậy và cấp quyền rộng cho kernel. Đọc kế hoạch dry-run trước, chỉ chọn provider bạn dùng và không đưa API key hoặc thông tin bí mật vào prompt hay file chia sẻ.
III.Cài đặt từng bước
- Kiểm tra môi trườngXác nhận Node.js, tmux và tài khoản provider đáp ứng yêu cầu
- Cài skill rigsĐể Claude Code hoặc Codex hướng dẫn quá trình cài OpenRig
- Cài CLICài @openrig/cli và xem trước thay đổi setup
- Chạy setupThêm tích hợp cần thiết cho provider và workspace
- Mở OpenRigKhởi động daemon, mở operator và chọn team
- Giao việc đầu tiênKiểm tra seat rồi gửi một mục tiêu có giới hạn
A.Kiểm tra Node.js, tmux và tài khoản
Mở Terminal trên macOS hoặc Linux. Nếu dùng Windows, mở một terminal bên trong WSL2, không chạy trực tiếp ở PowerShell native. Kiểm tra Node.js trước vì README yêu cầu phiên bản 22 hoặc 24.
node --version
tmux -VKết quả node --version cần là 22 hoặc 24. Nếu Linux đang có Node.js cũ, hãy cài phiên bản được hỗ trợ bằng nvm hoặc NodeSource theo hướng dẫn trong README. Trên macOS Apple silicon, chọn Node.js 22.
Tiếp theo, kiểm tra đúng provider bạn sẽ dùng. Không cần cài hoặc đăng nhập provider không sử dụng.
claude --version
claude auth statusHoặc với Codex:
codex --version
codex login statusNếu chưa đăng nhập, dùng lệnh tương ứng:
claude auth login
codex loginBạn chỉ cần chạy nhóm lệnh của provider đã chọn. Nếu lệnh báo chưa cài CLI hoặc tài khoản chưa đăng nhập, hãy xử lý bước đó trước khi setup OpenRig.
B.Cài skill cho Claude Code hoặc Codex
Đứng trong thư mục project bạn muốn OpenRig hỗ trợ. Để Claude Code tự hướng dẫn cài đặt, chạy:
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.12/skills/rigs --skill rigs --agent claude-codeNếu dùng Codex, chạy:
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.12/skills/rigs --skill rigs --agent codexSau đó mở Claude Code và gõ /rigs, hoặc mở Codex và gõ $rigs. Hãy nói rõ bạn muốn xây gì hoặc muốn thực hiện thay đổi nào trong project. Skill sẽ cho agent trình bày những lệnh và thay đổi dự kiến trước khi thực hiện.
Đây là cách phù hợp nếu bạn muốn coding agent hướng dẫn toàn bộ quy trình. Nếu muốn tự gõ lệnh, chuyển sang bước tiếp theo.
C.Cài CLI theo cách tự thực hiện
Cách cài nhanh dùng script của bản phát hành được README chỉ định. Trước tiên, chạy chế độ xem trước. Lệnh này in kế hoạch và không thay đổi máy:
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.12/scripts/install.sh | sh -s -- --dry-runNếu kế hoạch phù hợp, chạy cài đặt:
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.12/scripts/install.sh | shScript kiểm tra Node.js và npm, cài @openrig/cli bằng npm install -g, kiểm tra Node.js và SQLite, sau đó chạy rig setup --dry-run rồi rig setup.
Nếu muốn chia nhỏ các bước, cài CLI trước:
npm install -g @openrig/cli
rig setup --dry-runREADME cũng cho phép dùng Bun:
bun add -g @openrig/cliDù dùng Bun, OpenRig vẫn chạy trên Node.js, nên bạn vẫn phải cài Node.js 22 hoặc 24. Bun có thể chặn postinstall script của package. Khi đó, bước kiểm tra Node.js và SQLite không chạy lúc cài.
Với npm 11 trở lên, bạn có thể thấy cảnh báo npm warn install-scripts nhắc đến @openrig/cli. README cho biết đây là tình huống có thể xảy ra và CLI vẫn dùng được. Nếu cần chạy kiểm tra thủ công, dùng:
node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"D.Chọn provider và chạy setup
Để xem trước các thay đổi, dùng:
rig setup --dry-runNếu bạn chỉ dùng Claude Code, giới hạn setup bằng:
rig setup --providers claudeNếu chỉ dùng Codex:
rig setup --providers codexNếu không truyền --providers, rig setup kiểm tra cả Claude Code và Codex, đồng thời có thể cài provider còn thiếu. Vì vậy, người mới nên dùng lựa chọn provider rõ ràng để tránh các bước không cần thiết.
Khi chạy setup, OpenRig có thể thêm block vào ~/.tmux.conf, cài tmux trên macOS bằng Homebrew và cài Herdr nếu bạn không dùng --no-herdr. Nó cũng có thể thêm hook, trust settings, skill, plugin và hướng dẫn quản lý vào project.
Nếu setup dừng ở trạng thái INSTALLED, SETUP NOT COMPLETE, hãy đọc bước được báo lỗi, đăng nhập provider nếu cần rồi chạy lại:
rig setupCLI đã cài thì không cần cài lại.
E.Mở daemon, operator và dashboard
Sau khi setup xong, khởi động daemon:
rig daemon startMở kernel operator trong cửa sổ mới:
rig terminal open saved:kernel --windowBạn cũng có thể mở dashboard:
rig tui--window có thể mở tab hoặc cửa sổ terminal mới, hoặc mở một không gian trong phiên Herdr hiện tại. Màn hình nhỏ có thể làm giao diện chật; README lưu ý cửa sổ 80×24 không đủ thoải mái.
Nếu không mở được cửa sổ, dùng dashboard chia sẻ:
rig tui --sharedLưu ý rằng rig tui --shared chỉ là phương án dashboard và không hiển thị cuộc trò chuyện với operator. Nếu chạy qua SSH hoặc môi trường headless, bạn có thể phải tự mở terminal mới và attach theo đúng lệnh mà agent cài đặt cung cấp.
F.Chọn team và giao việc đầu tiên
Kernel operator sẽ hỏi bạn muốn xây gì, đề xuất một team và điều chỉnh team theo provider đã đăng nhập. Các lựa chọn chính là starter, workshop và factory.
Nếu muốn tự khởi động team starter, chạy trong thư mục repository:
cd /path/to/your/repository
rig specs preview starter --kind rig
rig up starter --cwd . --plan
rig up starter --cwd .rig specs preview cho bạn xem đặc tả team. rig up ... --plan xem kế hoạch trước khi chạy thật. Khi đã kiểm tra, lệnh cuối khởi động team trong thư mục hiện tại.
Kiểm tra các seat đã sẵn sàng:
rig ps --nodes --rig starterNếu một seat dừng ở màn hình xác thực, trust hoặc permission, hãy xử lý prompt đó trước. Nếu seat đã qua prompt nhưng chưa nhận ngữ cảnh khởi động, rig ps sẽ hiển thị lệnh rig seat continue <seat> tương ứng.
Khi team sẵn sàng, gửi một việc có phạm vi rõ:
rig send dev-build@starter 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-review in this rig to check the exact candidate, and record the result and how I can try it.'
rig queue list --destination dev-build@starter --limit 1000Thay phần <one useful change> bằng một thay đổi cụ thể. rig send chỉ gửi tin nhắn; nó không tự tạo queue item. Builder phải ghi task theo yêu cầu trong tin nhắn.
IV.Kiểm tra đã chạy được chưa
Cài đặt cơ bản thành công khi node --version trả về 22 hoặc 24, tmux -V chạy được và provider bạn chọn trả về trạng thái đăng nhập hợp lệ.
Sau setup, rig setup --dry-run phải hiển thị kế hoạch không có lỗi chặn. Khi chạy thật, OpenRig có thể báo hoàn tất hoặc chỉ rõ bước còn thiếu. Nếu thấy INSTALLED, SETUP NOT COMPLETE, đó là dấu hiệu CLI đã cài nhưng setup chưa hoàn tất.
Bạn cũng kiểm tra bằng cách mở daemon và terminal operator:
rig daemon start
rig terminal open saved:kernel --windowDấu hiệu dễ nhận biết nhất là bạn nhìn thấy OpenRig view và đang nói chuyện được với operator. Operator sẽ giúp chọn team đầu tiên.
Sau khi khởi động team, chạy:
rig ps --nodes --rig starterCác seat cần vượt qua prompt đăng nhập, trust hoặc quyền. Gửi một nhiệm vụ thử nghiệm nhỏ, sau đó xem queue:
rig queue list --destination dev-build@starter --limit 1000Nếu builder trả về ID task, kết quả kiểm tra và cách bạn thử thay đổi, quy trình cơ bản đã hoạt động.
V.Dùng vào việc thật
A.Chủ shop muốn chỉnh trang bán hàng
Một chủ shop có repository website bán hàng và muốn sửa một thay đổi nhỏ, chẳng hạn điều chỉnh nội dung nút thanh toán hoặc cải thiện thông báo khi giỏ hàng trống. Thay vì giao yêu cầu chung chung như “làm website tốt hơn”, hãy gửi một mục tiêu có giới hạn:
rig send dev-build@starter 'Implement one useful change: improve the empty-cart message for Vietnamese customers. Track the task in the queue, keep the change local, verify the behavior, ask dev-review to check the exact candidate, and return the task ID plus how I can try it.'Builder thực hiện thay đổi trong repository, kiểm tra hành vi và nhờ reviewer xem đúng candidate. Chủ shop nhận được kết quả cụ thể để mở website và thử lại.
B.Nhân viên văn phòng muốn tự động hóa một quy trình
Một nhân viên có project nội bộ và muốn thêm một bước xuất báo cáo. Bạn có thể yêu cầu operator chọn team phù hợp, sau đó giao việc cho builder với đầu vào rõ ràng: file nào liên quan, dữ liệu mẫu nào được dùng và kết quả cần kiểm tra.
Ví dụ, nội dung gửi có thể là: “Thêm chức năng xuất báo cáo theo bộ lọc hiện có, chỉ thay đổi trong thư mục báo cáo, dùng dữ liệu mẫu của project, ghi task vào queue và nhờ reviewer kiểm tra file đầu ra.”
Cách nói này giúp team biết giới hạn công việc. Bạn có thể xem queue bằng:
rig queue list --destination dev-build@starter --limit 1000Kết quả nên gồm thay đổi đã tạo, cách chạy thử và nhận xét của reviewer.
C.Dev mới muốn có người xây và người review
Một dev mới có thể dùng starter cho một thay đổi đơn lẻ. Trước khi giao việc, xem kế hoạch và trạng thái seat:
rig specs preview starter --kind rig
rig ps --nodes --rig starterSau đó gửi yêu cầu theo mẫu:
rig send dev-build@starter 'Implement <one bounded change> in this repository. Return the queue ID, keep the work local, verify the behavior, ask dev-review to inspect the exact candidate, and explain how I can try it.'Điểm quan trọng là thay đổi phải “bounded”, tức có phạm vi cụ thể. Khi nhận kết quả, hãy đọc artifact và review của đúng candidate trước khi giao thay đổi kế tiếp.
D.Nhóm sản phẩm cần nhiều vai trò lâu dài
Nếu một repository cần lead, builder, QA và reviewer làm việc thường xuyên, operator có thể đề xuất workshop. Với công việc sản phẩm kéo dài và cần nhiều reviewer độc lập, factory có bảy agent gồm lead, advisor, build, QA, design và hai reviewer.
Bạn nên mô tả sản phẩm, repository, phạm vi quyền và kết quả cần đạt trong cuộc trò chuyện với kernel operator. Team sẽ giúp bạn chọn cấu hình phù hợp với provider đã đăng nhập. Nếu chỉ có một provider, hãy yêu cầu operator điều chỉnh team thay vì cố cài thêm tài khoản.
Một thay đổi nhỏ, có task ID và được reviewer kiểm tra, đáng tin hơn một lời hứa lớn không có điểm kiểm chứng.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Node.js không đúng phiên bản
Nếu node --version trả về phiên bản ngoài 22 hoặc 24, setup có thể không đáp ứng yêu cầu. Trên Linux, Node.js của hệ điều hành có thể cũ; hãy cài phiên bản được hỗ trợ bằng nvm hoặc NodeSource theo hướng dẫn README. Trên Apple silicon, dùng Node.js 22.
B.Đang chạy Windows native
README chỉ hỗ trợ macOS, Linux và WSL2 trên Windows. Nếu đang chạy PowerShell hoặc Command Prompt native, hãy chuyển sang môi trường WSL2. Không nên tự suy ra rằng bản Windows native sẽ hoạt động chỉ vì lệnh CLI có vẻ đơn giản.
C.Thiếu tmux hoặc Herdr hiển thị không đúng
Kiểm tra tmux bằng tmux -V. OpenRig có thể cài tmux trên macOS bằng Homebrew trong quá trình setup. Herdr có thể hiển thị panel lần đầu hoặc bị chật trong cửa sổ 80×24; hãy mở terminal lớn hơn và làm theo kiểm tra mà OpenRig đưa ra.
D.Provider chưa đăng nhập hoặc seat dừng ở prompt
Chỉ chọn provider bạn đã đăng nhập bằng --providers claude hoặc --providers codex. Kiểm tra lại bằng claude auth status hoặc codex login status. Nếu seat dừng trước khi nhận ngữ cảnh, chạy rig ps và dùng lệnh rig seat continue <seat> mà hệ thống hiển thị sau khi bạn xử lý prompt.
E.Setup thay đổi cấu hình ngoài dự kiến
Hãy luôn chạy rig setup --dry-run trước. OpenRig có thể sửa ~/.tmux.conf, cấu hình Codex, cấu hình Claude Code, file settings trong project, AGENTS.md hoặc CLAUDE.md, đồng thời thêm hook và skill. Sao lưu trước khi setup; README nói OpenRig không đảm bảo có thể bảo toàn hoặc rollback các file này.
F.Không mở được cửa sổ operator
Daemon có thể đã chạy nhưng terminal mới không mở được do môi trường desktop, quyền Automation hoặc SSH headless. Dùng rig tui --shared để xem dashboard, rồi hỏi agent cài đặt lệnh attach chính xác cho phiên operator hiện tại. Đóng cửa sổ xem không có nghĩa là phải khởi động lại team.
VII.Có nên dùng không
Bạn nên dùng OpenRig nếu thường xuyên làm việc với repository, muốn nhiều coding agent phối hợp, cần team có vai trò ổn định hoặc muốn một thay đổi được builder thực hiện rồi reviewer kiểm tra. Các team starter, workshop và factory giúp bạn bắt đầu theo quy mô khác nhau.
Điểm mạnh là quy trình có cấu trúc: có operator, team, seat, queue, dashboard và trạng thái persistent. OpenRig cũng hỗ trợ cả Claude Code và Codex trong cùng hệ thống, trong khi chỉ cần một provider để khởi đầu.
Giới hạn là cài đặt không nhẹ như chạy một CLI đơn lẻ. Bạn cần Node.js đúng phiên bản, tmux, môi trường Unix hoặc WSL2, tài khoản coding agent và có thể phải xử lý quyền, trust, hook cùng các thay đổi cấu hình. README cũng cho biết automated tests chưa chạy trên WSL2.
Bạn nên chọn công cụ khác nếu chỉ cần một agent sửa nhanh một file, không muốn thay đổi cấu hình máy, không có tmux hoặc muốn chạy native Windows. Khi đó, dùng trực tiếp Claude Code hoặc Codex có thể đơn giản hơn.
OpenRig được phát hành dưới giấy phép Apache-2.0 và là phần mềm mã nguồn mở. Tuy vậy, README không khẳng định toàn bộ việc sử dụng provider là miễn phí; bạn vẫn cần tài khoản và quyền truy cập phù hợp với Claude Code hoặc Codex. Hãy bắt đầu bằng starter, đọc kế hoạch dry-run, giao một thay đổi nhỏ và chỉ mở rộng team khi quy trình đầu tiên đã rõ ràng.
Câu hỏi thường gặp
OpenRig có miễn phí không?
OpenRig là phần mềm mã nguồn mở và repo dùng giấy phép Apache-2.0. Tuy nhiên, README không khẳng định chi phí của Claude Code, Codex hoặc tài khoản provider, nên bạn vẫn cần tài khoản và quyền truy cập phù hợp.
Có cần cả Claude Code và Codex không?
Không. Chỉ một provider là đủ để bắt đầu. Bạn có thể dùng `--providers claude` hoặc `--providers codex` để setup đúng provider đang sử dụng.
OpenRig có chạy được trên Windows không?
Windows native chưa được hỗ trợ. README chỉ ra hướng dùng WSL2 trên Windows; các bài kiểm thử tự động của OpenRig hiện chưa chạy trên WSL2.
Có cần GPU không?
Tư liệu được cung cấp không nói OpenRig yêu cầu GPU. README chỉ nêu Node.js 22 hoặc 24, tmux, macOS hoặc Linux hoặc WSL2 và một tài khoản Claude Code hoặc Codex đã đăng nhập.
OpenRig thay đổi những gì trên máy?
Setup có thể thêm cấu hình vào `~/.tmux.conf`, hook và trust settings cho Codex hoặc Claude Code, skill, plugin và hướng dẫn vào project. README khuyến nghị sao lưu trước vì OpenRig không đảm bảo có thể bảo toàn hoặc rollback các file này.
Dùng OpenRig có an toàn không?
Mức quyền phụ thuộc team và thiết lập. Kernel mặc định có thể được cấp quyền rộng; team `workshop` cũng được mô tả là có quyền rộng. Bạn nên đọc dry-run, kiểm tra permission policy và không đưa thông tin bí mật vào prompt hoặc file chia sẻ.
Nếu chỉ muốn giao một việc nhỏ thì nên chọn team nào?
README mô tả `starter` cho một thay đổi có giới hạn, với builder và reviewer. Bạn có thể xem đặc tả, chạy team rồi gửi một mục tiêu cụ thể bằng `rig send`.


