# OpenRig: dựng đội agent Claude Code và Codex chạy bền — hướng dẫn cài đặt và dùng

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

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

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.

```repo
- repo | mvschwarz/openrig
- kind | CLI
- desc | 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.
- stars | 8.8k
- lang | TypeScript
- license | Apache-2.0
```

## 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ế.

### 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.

### 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ó 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.

### 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.

### 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.

## 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 setup` có 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.

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

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

```steps
- Kiểm tra Node và tmux | Chạy node --version, tmux -V để chắc đã có Node 22 hoặc 24
- Cài OpenRig | Dùng script cài hoặc npm install -g @openrig/cli
- Chạy rig setup | Xem 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ấp | Dùng claude auth login hoặc codex login nếu chưa đăng nhập
- Mở giao diện | Chạ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.

### 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:

```bash
node --version
tmux -V
```

Kế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.

### 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:

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

Script 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:

```bash
npm install -g @openrig/cli
rig setup --dry-run
```

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

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

```bash
rig setup --providers claude
```

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

### Đă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:

```bash
claude --version
claude auth status
# hoặc
codex --version
codex login status
```

Chưa đăng nhập thì chạy `claude auth login` hoặc `codex login`.

### Mở giao diện và nói chuyện với operator

```sh
rig daemon start
rig terminal open saved:kernel --window
```

Lệ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.

### 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:

```sh
# 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 codex
```

Sau đó 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.

## 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:

```bash
rig --version
tmux -V
rig ps --nodes --rig starter
```

- `rig --version` cho 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 doctor` kiể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 starter` xem trạng thái các agent sau khi bạn khởi động đội `starter`. 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.

## 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.

### 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:

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

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

Bạ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

### 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.

### 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.

### 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:

```bash
rig daemon start
rig terminal open saved:kernel --window
```

Các cuộc trò chuyện hiện có được giữ nguyên.

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

### 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.

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

### 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:

```bash
node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"
```

### 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.

### 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.

### 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 đó.

## 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.
