OpenRig: dựng đội agent Claude Code và Codex chạy bền — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về mvschwarz/openrig — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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à phần mềm mã nguồn mở (lệnh `rig`) để biến nhiều phiên Claude Code, Codex thành một đội agent chạy bền, có vai trò và hàng đợi việc. Bạn nói với một agent trưởng về kết quả muốn có, nó điều phối các agent còn lại. Cài bằng npm hoặc một script, cần Node.js 22/24 và tmux, chạy trên macOS, Linux hoặc WSL2.
OpenRig là phần mềm mã nguồn mở để dựng và chạy một "mạng lưới agent" của riêng bạn. Nó biến các agent lập trình AI như Claude Code và Codex, vốn thường chỉ là một đống cửa sổ terminal rời rạc, thành một đội làm việc có tổ chức và chạy bền. Bạn định nghĩa đội bằng YAML, rồi khởi động bằng một lệnh.
Cách dùng chính là nói chuyện với một agent trưởng về kết quả bạn muốn. Agent trưởng điều phối các agent chuyên môn, rồi mang về kết quả và những quyết định cần bạn xem. Bạn có thể bắt đầu nhỏ: một repo và một thay đổi hữu ích, sau đó giữ nguyên công việc và ngữ cảnh của đội ở cùng một chỗ.
Repo này hợp với lập trình viên đã quen Claude Code hoặc Codex và muốn chạy nhiều agent phối hợp. Bạn không cần dùng cả hai, một tài khoản là đủ để bắt đầu. Điểm đáng giá nhất là Claude Code và Codex nằm trong cùng một đội và được quản lý như một hệ thống. Hiện repo có khoảng 8.835 sao và 750 fork, giấy phép Apache-2.0.
mvschwarz/openrig
OpenRig là công cụ mã nguồn mở giúp dựng đội agent AI từ Claude Code và Codex, có vai trò rõ ràng, ngữ cảnh chung và công việc có người nhận.
I.OpenRig làm được gì
Tác giả dùng một ví von dễ nhớ: harness bọc một model, còn rig bọc các harness của bạn. Dưới đây là những thứ bạn nhận được trong thực tế.
A.Khai báo đội agent bằng YAML
Bạn mô tả đội gồm những agent nào, vai trò gì. Lần sau chỉ cần khởi động lại, không phải mở từng cửa sổ và dặn lại từ đầu.
B.Claude Code và Codex chung một đội
Đội starter đi kèm có một builder chạy Claude Code và một reviewer chạy Codex. Một agent viết, một agent khác (dùng model khác) soát lại, nên bạn đỡ phải tự đọc từng dòng thay đổi.
C.Có agent trưởng và hàng đợi việc
Bạn giao một kết quả cụ thể, agent ghi công việc vào hàng đợi (queue). Bạn xem được ai đang giữ việc gì bằng lệnh rig queue list, thay vì lục lại lịch sử chat.
D.Ba đội dựng sẵn
OpenRig có sẵn ba đội để chọn:
starter: một builder Claude Code và một reviewer Codex, cho một thay đổi gọn.workshop: gồm trưởng nhóm, builder, QA và reviewer, cho công việc kéo dài trong một repo.factory: bảy agent gồm trưởng nhóm, cố vấn, build, QA, thiết kế và hai reviewer độc lập, cho sản phẩm làm lâu dài.
E.Giao diện xem đội
Lệnh rig terminal open saved:kernel --window mở màn hình gồm bảng điều khiển và khung trò chuyện với "operator" (agent điều hành hệ thống). rig tui là bảng điều khiển đội.
II.Cần chuẩn bị gì
Theo README, bạn cần:
- Hệ điều hành: macOS hoặc Linux. Trên Windows, dùng WSL2. Windows gốc (native) chưa được hỗ trợ. README cũng nói bộ kiểm thử tự động của OpenRig chưa chạy trên WSL2.
- Node.js: bản 22 hoặc 24 (trên Mac chip Apple silicon, dùng 22). Lệnh cài cần
npxđi kèm Node. Repo khai báo Node ^22 || ^24. - tmux: bắt buộc. Lệnh
rig setupcó thể cài tmux giúp bạn (bằng Homebrew trên macOS). - Tài khoản: một tài khoản Claude Code hoặc Codex đã đăng nhập. Một nhà cung cấp là đủ, không cần đăng ký thêm gói thứ hai.
Trên Linux, Node.js của bản phân phối có thể cũ (README nêu Ubuntu 24.04 đi kèm bản 18). Khi đó hãy cài bản phù hợp bằng nvm (nvm install 22) hoặc NodeSource.
README chưa nói về yêu cầu RAM hay GPU. Phần cứng cụ thể thì chưa có thông tin trong tư liệu.
OpenRig sửa khá nhiều thứ trên máy bạn: thêm một khối vào ~/.tmux.conf, ghi thiết lập tin cậy và hook cho Claude Code hoặc Codex, thêm skill vào ~/.claude/skills và ~/.agents/skills. README cũng nói OpenRig không đảm bảo hoàn tác được các file này, nên hãy sao lưu trước khi cài.
III.Cài đặt từng bước
- Kiểm tra Node và tmuxChạy node --version, tmux -V để chắc đã có Node 22 hoặc 24
- Cài OpenRigDùng script cài hoặc npm install -g @openrig/cli
- Chạy rig setupXem trước rồi áp dụng thiết lập, chọn nhà cung cấp Claude hoặc Codex
- Đăng nhập nhà cung cấpDùng claude auth login hoặc codex login nếu chưa đăng nhập
- Mở giao diệnChạy rig daemon start và rig terminal open saved:kernel --window
README có hai đường: nhờ agent cài hộ, hoặc tự gõ lệnh. Mình hướng dẫn đường tự gõ vì dễ kiểm soát hơn.
A.Kiểm tra Node.js và tmux
Mở terminal (trên Windows là cửa sổ WSL2, không phải PowerShell thường) và chạy:
node --version
tmux -VKết quả node --version phải là 22 hoặc 24. Nếu thấy số nhỏ hơn, cài lại Node bằng nvm trước khi làm tiếp. Nếu chưa có tmux, bạn vẫn có thể để rig setup cài giúp ở bước sau.
B.Cài OpenRig
Cách một lệnh: script cài của bản v0.7.12. Dòng đầu chỉ in kế hoạch và không thay đổi gì. Bạn nên chạy dòng đầu trước:
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.12/scripts/install.sh | sh -s -- --dry-run
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.12/scripts/install.sh | shScript này kiểm tra Node.js và npm, cài @openrig/cli bằng npm install -g, kiểm tra Node.js và SQLite, rồi chạy rig setup --dry-run và rig setup. Lưu ý: cách này cài và kiểm tra cả Claude Code lẫn Codex, và có thể cài giúp cái còn thiếu.
Nếu chỉ dùng một nhà cung cấp, hãy đi từng bước:
npm install -g @openrig/cli
rig setup --dry-runnpm install -g cài lệnh rig cho toàn máy. rig setup --dry-run cho bạn xem trước những gì setup sẽ làm mà chưa áp dụng.
Nếu bạn dùng Bun, README nêu lệnh bun add -g @openrig/cli. OpenRig vẫn chạy trên Node.js nên vẫn cần cài Node.js 22. Bun có thể chặn script postinstall, khi đó bước kiểm tra Node.js và SQLite sẽ không chạy lúc cài.
C.Chạy rig setup theo nhà cung cấp của bạn
README nói hãy truyền lựa chọn bằng --providers claude hoặc --providers codex, để nhà cung cấp còn lại hiện là "không chọn" thay vì báo lỗi. Dạng chung là rig setup --providers <lựa chọn>:
rig setup --providers claudeThay claude bằng codex nếu bạn dùng Codex. Nếu không muốn cài Herdr, README cho biết có cờ --no-herdr.
Nếu cuối cùng thấy dòng INSTALLED, SETUP NOT COMPLETE, nghĩa là CLI đã cài nhưng setup chưa xong. Đọc chỗ báo "Fix", làm theo rồi chạy lại rig setup. Không cần cài lại CLI.
D.Đăng nhập nhà cung cấp
Kiểm tra đúng nhà cung cấp bạn chọn, đừng đăng nhập cái không dùng:
claude --version
claude auth status
# hoặc
codex --version
codex login statusChưa đăng nhập thì chạy claude auth login hoặc codex login.
E.Mở giao diện và nói chuyện với operator
rig daemon start
rig terminal open saved:kernel --windowLệnh đầu bật tiến trình nền của OpenRig. Lệnh thứ hai mở cửa sổ (hoặc tab) mới để bạn trò chuyện với operator. README nói việc cài đặt xem như xong khi bạn đang nói chuyện được với operator.
F.Cách khác: nhờ agent cài hộ
Trong thư mục dự án, thêm skill rigs cho agent bạn đang dùng:
# Claude Code
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.12/skills/rigs --skill rigs --agent claude-code
# Codex
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.12/skills/rigs --skill rigs --agent codexSau đó gõ /rigs trong Claude Code, hoặc $rigs trong Codex, rồi nói bạn muốn dựng gì. Theo README, agent sẽ báo trước nó định chạy và thay đổi những gì, rồi mới cài.
IV.Kiểm tra đã chạy được chưa
Theo README, dấu hiệu rõ nhất là bạn mở được cửa sổ OpenRig và đang trò chuyện với operator. Bạn cũng có thể kiểm tra từng phần:
rig --version
tmux -V
rig ps --nodes --rig starterrig --versioncho biết bản đang cài. Nếu bạn đã có OpenRig, hãy dùng tag khớp với bản này khi cài skill.rig doctorkiểm tra phiên bản Node.js. README nói lệnh này chỉ kiểm tra Node.js.rig ps --nodes --rig starterxem trạng thái các agent sau khi bạn khởi động độistarter. Nếu agent dừng ở một màn hình đăng nhập, tin cậy hoặc cấp quyền, hãy xử lý màn hình đó trước khi giao việc.
Nếu cửa sổ không mở được, rig tui --shared là phương án chỉ hiện bảng điều khiển, không có khung trò chuyện với operator.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo cách dùng được mô tả trong README. Kết quả cụ thể phụ thuộc vào repo và tài khoản của bạn.
A.Lập trình viên giao một thay đổi nhỏ cho đội starter
Bạn có một repo và muốn thêm một tính năng gọn. Vào thư mục repo, xem trước đội rồi khởi động:
cd /path/to/your/repository
rig specs preview starter --kind rig
rig up starter --cwd . --plan
rig up starter --cwd .Lệnh --plan cho bạn xem kế hoạch trước, lệnh cuối mới thật sự bật đội. Rồi giao việc cho builder:
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 1000Bạn thay <one useful change> bằng việc thật của mình. Kết quả là một bản thay đổi đã được reviewer kiểm tra, kèm ghi chú cách thử. Lưu ý README nói gửi tin nhắn không tự tạo mục trong hàng đợi, builder mới là bên ghi công việc.
Đội agent chỉ đáng tin khi mỗi việc có người nhận và có người soát lại.
Ông T
B.Người dùng chỉ có một tài khoản
Bạn chỉ trả tiền cho Claude Code, không có Codex. Đội starter mặc định dùng cả hai. README hướng dẫn nhờ operator của kernel điều chỉnh: nó ghi một bản sao của đội cho đúng nhà cung cấp bạn có, cùng tên starter. Bạn chỉ cần nói với operator rằng bạn chỉ có Claude Code.
C.Chọn đội cho công việc dài hơi
Bạn đang làm một sản phẩm trong nhiều tuần. Hãy nói với operator bạn muốn xây gì. Theo README, nó sẽ hỏi, rồi đề xuất một trong ba đội. Với công việc liên tục trong một repo, workshop có trưởng nhóm, builder, QA và reviewer. Muốn bài bản hơn nữa thì có factory với bảy agent. Hãy đọc kỹ quyền truy cập của đội trước khi chọn, vì README nói workshop được cấp quyền rộng.
D.Quay lại làm tiếp sau khi đóng cửa sổ
Bạn lỡ đóng cửa sổ xem. README nói đóng cửa sổ xem không có nghĩa phải khởi động lại đội. Bạn chỉ cần mở lại:
rig daemon start
rig terminal open saved:kernel --windowCác cuộc trò chuyện hiện có được giữ nguyên.
VI.Lỗi hay gặp và cách xử lý
A.Node.js quá cũ
Trên Ubuntu, Node.js của bản phân phối có thể là bản 18, không đạt yêu cầu. Cài bản 22 bằng nvm (nvm install 22) rồi mở terminal mới. Nếu Mac của bạn không có quyền quản trị, README gợi ý cài nvm trong thư mục cá nhân, và chạy touch ~/.zshrc trước nếu máy chưa có file này.
B.Cài xong nhưng báo SETUP NOT COMPLETE
Đây là chuyện thường gặp. Đọc phần "Fix" mà rig setup in ra, làm theo rồi chạy lại rig setup. Nếu chỉ còn lỗi đăng nhập nhà cung cấp, hãy đăng nhập bằng claude auth login hoặc codex login.
C.npm cảnh báo bỏ qua postinstall
Từ npm 11, có thể thấy dòng npm warn install-scripts nhắc tới @openrig/cli. README nói đó là bình thường, CLI vẫn chạy, chỉ bước kiểm tra Node.js và SQLite bị bỏ qua. Muốn chạy bước đó thì dùng lệnh sau:
node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"D.Agent đứng yên ở màn hình xin quyền
Một agent có thể dừng ở lời nhắc đăng nhập, tin cậy hoặc cấp quyền. Chạy rig ps, xử lý lời nhắc đó. Nếu agent dừng trước khi nhận ngữ cảnh khởi động, rig ps sẽ hiện lệnh rig seat continue <seat> để gửi tiếp.
E.Cửa sổ không mở hoặc bị chật
Trên máy từ xa qua SSH (không có màn hình), hoặc khi macOS cần bạn cho phép Automation, cửa sổ có thể không mở. Hãy tự mở một cửa sổ terminal mới rồi chạy lệnh gắn vào. Cửa sổ 80×24 cũng khá chật, hãy phóng to ra. Dưới 120 cột, operator chiếm trọn trang đầu.
F.Chạy trên Windows gốc
Windows gốc chưa được hỗ trợ. Hãy cài WSL2 rồi làm mọi bước bên trong đó.
VII.Có nên dùng không
Điểm mạnh. OpenRig cho bạn một đội agent có vai trò, hàng đợi việc và giao diện theo dõi, thay vì một đống cửa sổ terminal. Dùng chung được Claude Code và Codex, nên một agent viết và một agent khác soát lại. Mã nguồn mở theo giấy phép Apache-2.0, và README cho thấy tác giả khá kỹ về việc nói rõ nó sửa gì trên máy bạn. Repo cũng được cập nhật trong vài tháng gần đây.
Giới hạn. Cài đặt không nhẹ: cần tmux, Node 22/24 và một tài khoản agent đã đăng nhập. Nó sửa cấu hình của Claude Code, Codex và tmux, nên phải sao lưu trước. Quyền mặc định của kernel khá rộng: trên Codex là truy cập đầy đủ không hỏi duyệt, còn đội workshop cũng được cấp quyền rộng. Windows chỉ chạy qua WSL2. Chi phí dùng agent tính theo tài khoản Claude Code hoặc Codex của bạn, README không nói OpenRig tự giảm chi phí đó.
Khi nào chọn cách khác. Nếu bạn chỉ cần một agent làm một việc ngắn, cứ dùng thẳng Claude Code hoặc Codex, không cần thêm lớp điều phối. Nếu bạn dùng Windows gốc và không muốn dùng WSL2, OpenRig chưa phù hợp. Còn nếu bạn đã thấy mình mở nhiều phiên agent và mất dấu ai đang làm gì, đây là lúc đáng thử, bắt đầu với đội starter trên một thay đổi nhỏ.
Câu hỏi thường gặp
OpenRig có miễn phí không?
Bản thân OpenRig là mã nguồn mở theo giấy phép Apache-2.0. Tuy nhiên bạn cần một tài khoản Claude Code hoặc Codex đang dùng được, và chi phí của tài khoản đó do bạn tự chịu. README nói không cần đăng ký thêm gói thứ hai ngoài tài khoản bạn đã có.
OpenRig có chạy trên Windows không?
Windows gốc (native) chưa được hỗ trợ. Trên Windows bạn dùng WSL2, đây là đường README cho là được hỗ trợ. README cũng ghi bộ kiểm thử tự động của OpenRig chưa chạy trên WSL2.
Tôi chỉ có Claude Code (hoặc chỉ có Codex), có dùng được không?
Được. Một nhà cung cấp là đủ để bắt đầu. Đội starter mặc định dùng cả hai, nhưng bạn nhờ operator của kernel điều chỉnh để nó ghi một bản sao đội cho đúng nhà cung cấp bạn có. Khi chạy setup, bạn dùng cờ --providers claude hoặc --providers codex.
Cần cài những gì trước?
Cần Node.js 22 hoặc 24 (bản 22 nếu dùng Mac Apple silicon), tmux, macOS hoặc Linux (hoặc WSL2 trên Windows) và một tài khoản Claude Code hoặc Codex đã đăng nhập. rig setup có thể cài giúp tmux. README chưa nêu yêu cầu RAM hay GPU.
OpenRig có thay đổi gì trên máy tôi? Có an toàn không?
Có. Setup thêm một khối vào ~/.tmux.conf, ghi thiết lập tin cậy và hook cho Claude Code hoặc Codex, và thêm skill vào thư mục skills của bạn. Kernel mặc định có quyền rộng hơn đội thường, ví dụ trên Codex là truy cập đầy đủ không hỏi duyệt. README khuyên sao lưu trước vì không đảm bảo hoàn tác được các file này.
OpenRig khác gì việc tự mở nhiều cửa sổ Claude Code?
OpenRig tổ chức các agent thành một đội có vai trò, hàng đợi việc và ngữ cảnh dùng chung, có agent trưởng điều phối và có giao diện theo dõi. Bạn không phải tự quản từng phiên terminal. Tư liệu chưa có so sánh chi tiết với các công cụ điều phối khác.
Dữ liệu của tôi đi đâu?
README nói OpenRig ghi trạng thái, tích hợp nhà cung cấp và file làm việc ngay trên máy bạn như một phần của setup. Phần README còn lại về dữ liệu đã bị cắt nên mình chưa có thêm thông tin. Công việc của agent vẫn đi qua tài khoản Claude Code hoặc Codex bạn đang dùng.


