# 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ở giúp biến nhiều phiên agent lập trình (Claude Code, Codex) thành một đội làm việc bền vững, có vai trò và bối cảnh chung. Bạn cài bằng npm hoặc một script, rồi nói chuyện với agent điều phối để giao việc. Cài không quá khó nhưng cần Node.js 22 hoặc 24, tmux, macOS hoặc Linux (Windows dùng WSL2).

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

OpenRig là một công cụ dòng lệnh mã nguồn mở để dựng và vận hành "đội agent" của riêng bạn. Thay vì mở một đống cửa sổ terminal, mỗi cửa sổ chạy một AI lập trình rời rạc, OpenRig gom chúng thành một nhóm có tổ chức: có người dẫn đầu, có người xây, có người kiểm tra, và mọi thứ nằm ở những địa chỉ cố định để lần sau quay lại vẫn thấy.

Bạn khai báo đội bằng YAML, rồi khởi động bằng một lệnh. Claude Code và Codex có thể nằm chung một đội và được quản lý như một hệ thống. Bạn chỉ cần nói với agent đứng đầu về kết quả mình muốn; nó sẽ điều phối các agent chuyên trách và quay lại báo kết quả, kèm những quyết định cần bạn xem.

Repo này hợp với lập trình viên đã quen Claude Code hoặc Codex và muốn đi xa hơn một phiên chat đơn lẻ. Hiện repo có khoảng 8835 sao và 750 fork, viết bằng TypeScript, giấy phép Apache-2.0. Điểm đáng giá nhất là có sẵn đội mẫu: bạn chọn một đội, giao một thay đổi nhỏ trong repository của mình, và có luôn một agent khác kiểm tra kết quả.

```repo
- repo | mvschwarz/openrig
- kind | CLI
- desc | OpenRig cho bạn khai báo đội agent bằng YAML, gồm Claude Code và Codex, rồi khởi động cả đội bằng một lệnh và quản lý như một hệ thống.
- stars | 8.8k
- lang | TypeScript
- license | Apache-2.0
```

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

### Khai báo cả đội bằng YAML

Một "rig" là lớp bọc bên ngoài các harness (Claude Code, Codex). Bạn mô tả đội một lần, sau đó khởi động lại bất cứ lúc nào bằng một lệnh. Lợi ích thực tế: không phải nhớ mở agent nào, ở thư mục nào, với vai trò gì.

### Trộn Claude Code và Codex trong cùng một đội

Đội mẫu `starter` 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 soát, nên bạn bớt phải tự đọc lại từng dòng.

### Agent điều phối và việc có chủ

Bạn nói chuyện với một agent đứng đầu (gọi là operator). Nó giúp chọn đội phù hợp, giao việc cho agent chuyên trách và theo dõi qua hàng đợi (queue). Mỗi việc có người chịu trách nhiệm và có thể tra lại.

### Ba đội dựng sẵn

- `starter`: một builder Claude Code và một reviewer Codex, cho một thay đổi có giới hạn.
- `workshop`: gồm lead, builder, QA và reviewer, cho công việc liên tục trong một repository.
- `factory`: bảy agent gồm lead, advisor, build, QA, design và hai reviewer độc lập, cho sản phẩm làm dài hơi.

### Giao diện theo dõi

Lệnh `rig tui` mở bảng điều khiển của đội. Khi bạn mở cửa sổ operator, bảng này và khung chat với operator nằm cạnh nhau (từ 120 cột trở lên), nên nhìn được cả đội đang làm gì.

## Cần chuẩn bị gì

Theo README, bạn cần:

- Node.js 22 hoặc 24 (package.json yêu cầu `^22 || ^24`). Máy Mac chip Apple silicon nên dùng Node.js 22.
- tmux.
- macOS hoặc Linux. Trên Windows dùng WSL2; Windows gốc (native) chưa được hỗ trợ.
- Một tài khoản Claude Code hoặc Codex đã đăng nhập. Chỉ cần một trong hai là đủ để bắt đầu.

Lưu ý với Linux: Node.js đi kèm bản phân phối có thể cũ (README nêu Ubuntu 24.04 là bản 18). Khi đó hãy cài bản phù hợp bằng nvm (`nvm install 22`) hoặc NodeSource.

README cũng nói bộ kiểm thử tự động của OpenRig chưa chạy trên WSL2. Vì vậy người dùng Windows nên coi đây là đường đi có hỗ trợ nhưng còn mới.

```note
OpenRig sửa khá nhiều thứ trên máy bạn: thêm khối cấu hình vào ~/.tmux.conf, ghi thiết lập tin cậy và hook cho Claude Code/Codex, thêm skill vào ~/.claude/skills và ~/.agents/skills. README khuyên sao lưu các file này trước. Operator mặc định còn có quyền rộng hơn đội dự án, nên hãy đọc kỹ mục quyền hạn trong README trước khi cài.
```

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

```steps
- Kiểm tra Node | Chạy node --version, phải ra 22 hoặc 24
- Chọn cách cài | Nhờ agent cài bằng skill rigs, hoặc chạy script, hoặc npm
- Chạy thử không thay đổi | Dùng rig setup --dry-run để xem trước
- Đăng nhập nhà cung cấp | Claude Code hoặc Codex, chọn một
- Mở OpenRig | Khởi động daemon rồi mở cửa sổ operator
```

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

Mở terminal (trên Windows là terminal của WSL2) và chạy:

```bash
node --version
```

Kết quả phải bắt đầu bằng 22 hoặc 24. Nếu ra số nhỏ hơn, cài lại Node bằng nvm như mục trên rồi kiểm tra lại.

### Bước 2: Chọn một trong ba cách cài

**Cách A: nhờ agent của bạn cài.** 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 xây gì. Theo README, agent sẽ báo trước nó định chạy và thay đổi gì, cài OpenRig, mở giao diện và chuyển mục tiêu của bạn cho operator.

**Cách B: dùng script cài.** Script kiểm tra Node.js và npm, cài `@openrig/cli` bằng `npm install -g`, rồi chạy `rig setup --dry-run` và `rig setup`. Dòng đầu chỉ in kế hoạch và không thay đổi gì, nên bạn chạy dòng đó 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
```

Nếu bước cuối chưa xong, script báo `INSTALLED, SETUP NOT COMPLETE`. Khi đó đọc phần Fix được nêu rồi chạy lại `rig setup`; không cần cài lại CLI.

**Cách C: từng bước bằng tay.**

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

Lệnh đầu cài CLI toàn cục (có hai lệnh `rig` và `openrig-tui`). Lệnh sau cho bạn xem trước những gì setup sẽ làm. Khi đã yên tâm, chạy `rig setup` thật.

Nếu chỉ dùng một nhà cung cấp, README khuyên đi từng bước và truyền lựa chọn, vì script một lệnh sẽ cài và kiểm tra cả hai:

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

Thay `claude` bằng `codex` nếu bạn dùng Codex. Setup còn có thể cài tmux (bằng Homebrew trên macOS) và Herdr, trừ khi bạn thêm `--no-herdr`.

Với npm 11 trở lên, bạn có thể thấy cảnh báo `npm warn install-scripts` nhắc tới `@openrig/cli`. README nói đây 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 tự chạy bước đó:

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

README cũng nhắc có thể cài bằng Bun với `bun add -g @openrig/cli`, nhưng OpenRig vẫn chạy trên Node.js nên bạn vẫn cần cài Node 22.

### Bước 3: Kiểm tra tmux và đăng nhập

Chỉ kiểm tra nhà cung cấp bạn chọn:

```bash
tmux -V
claude --version
claude auth status
codex --version
codex login status
```

Nếu chưa đăng nhập, chạy một trong hai lệnh dưới. README dặn đừng cài hay đăng nhập nhà cung cấp mà bạn không dùng:

```bash
claude auth login
codex login
```

### Bước 4: Khởi động daemon và mở OpenRig

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

Lệnh đầu bật daemon nếu nó đang tắt. Lệnh sau mở cửa sổ gồm bảng điều khiển và operator. Theo README, việc cài đặt xem như xong khi bạn đang nói chuyện được với operator. Nếu mở bằng SSH không có màn hình, bạn cần tự mở cửa sổ terminal mới và nhờ agent đưa lệnh gắn vào đúng phiên.

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

Có vài điểm để tự xác nhận, đều lấy từ README:

- `rig --version` in ra phiên bản đã cài.
- `rig doctor` kiểm tra phiên bản Node.js.
- `tmux -V` in ra phiên bản tmux, và lệnh `auth status` hoặc `login status` của nhà cung cấp bạn chọn báo đã đăng nhập.
- Lệnh `rig terminal open saved:kernel --window` mở được cửa sổ và bạn trò chuyện được với operator.

Nếu đã chạy đội mẫu, kiểm tra các agent có sẵn sàng không:

```bash
rig ps --nodes --rig starter
```

Nếu một agent dừng ở màn hình hỏi đăng nhập, tin cậy hoặc quyền, hãy trả lời câu hỏi đó trước khi giao việc. README nói `rig ps` sẽ hiện lệnh `rig seat continue <seat>` để gửi tiếp phần ngữ cảnh khởi động còn thiếu.

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

Dưới đây là các tình huống bám theo những gì README mô tả. Phần prompt là ví dụ minh hoạ của mình.

### Lập trình viên cần sửa một lỗi nhỏ có người soát

Bạn có một repository và một lỗi cần sửa. Bạn muốn một agent làm, một agent khác soát. Hãy dùng đội `starter` theo đường thủ công:

```bash
cd /path/to/your/repository
rig specs preview starter --kind rig
rig up starter --cwd . --plan
rig up starter --cwd .
```

Lệnh `preview` cho xem đội gồm những ai, `--plan` cho xem kế hoạch khởi động, và lệnh cuối mới thực sự bật đội. Sau đó 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 yêu cầu cụ thể 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ử. README lưu ý: gửi tin nhắn không tự tạo mục trong hàng đợi, builder mới là bên ghi lại nhiệm vụ.

> Một agent viết, một agent khác soát, và bạn chỉ đọc kết quả cuối cùng.
>
> — Ông T

### Người mới chưa biết chọn đội nào

Bạn chưa rõ nên dùng `starter`, `workshop` hay `factory`. Cứ mở cửa sổ operator rồi nói bạn muốn xây gì. README cho biết operator sẽ hỏi mục tiêu, đề xuất một trong ba đội và chỉnh cho khớp với nhà cung cấp bạn có. Kết quả là bạn không phải tự đọc tài liệu từng đội trước khi bắt đầu.

### Bạn chỉ có Claude Code, không có Codex

Đội `starter` mặc định dùng cả hai. README nói bạn chỉ cần nhờ operator chỉnh lại: nó tạo một bản sao của đội cho đúng nhà cung cấp bạn có, giữ nguyên tên. Prompt mẫu cho operator: "Mình chỉ có Claude Code, hãy chỉnh đội starter cho phù hợp." Kết quả là một đội chạy được mà không bắt bạn mua thêm gói nào.

### Công việc kéo dài trong một dự án

Nếu bạn làm liên tục trên một repository, README giới thiệu đội `workshop` với lead, builder, QA và reviewer. Bạn nói chuyện với `orch-lead@workshop` về kết quả mong muốn, lead phân việc. Đội này được cấp quyền rộng và bỏ qua các hộp thoại xin quyền, nên chỉ chọn khi bạn đã hiểu rõ điều đó. Mình chưa có thông tin chi tiết hơn về luồng làm việc của `workshop` ngoài phần tóm tắt trong README.

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

### Node.js sai phiên bản

Triệu chứng: cài xong nhưng `rig` báo lỗi, hoặc `rig doctor` than phiền về Node. Cách xử lý: chạy `node --version`, nếu không phải 22 hoặc 24 thì cài bằng nvm (`nvm install 22`). Trên Mac chip Apple silicon, README khuyên dùng bản 22.

### Máy Mac không có quyền quản trị, Homebrew bị từ chối

README hướng dẫn cài Node.js vào thư mục cá nhân bằng nvm. Chạy `touch ~/.zshrc` trước (tài khoản Mac mới chưa có file này, mà trình cài nvm chỉ tự ghi vào file đã tồn tại), rồi chạy lệnh cài nvm, mở terminal mới và chạy `nvm install 22`. Nếu trình cài nvm đòi công cụ dòng lệnh của Apple, chạy `xcode-select --install` rồi cài lại.

### Cài xong nhưng báo SETUP NOT COMPLETE

Đây là thông báo của script cài khi bước `rig setup` chưa hoàn tất. Đọc phần Fix được in ra, khắc phục (thường là thiếu công cụ hoặc chưa đăng nhập) rồi chạy lại `rig setup`. Không cần cài lại CLI.

### Cửa sổ OpenRig không mở được

Có thể do máy cần bạn cấp quyền Automation, do đang SSH không có màn hình, hoặc cửa sổ 80×24 quá chật. Với SSH, hãy mở một tab terminal mới và nhờ agent cho lệnh gắn đúng phiên. Phương án chỉ xem bảng điều khiển là `rig tui --shared`, nhưng nó không hiện cuộc trò chuyện với operator. Đóng cửa sổ xem không có nghĩa là bạn phải khởi động lại đội.

### Agent dừng ở hộp thoại xin quyền hoặc tin cậy

Dùng `rig ps --nodes --rig starter` để xem agent nào đang kẹt, trả lời hộp thoại, rồi dùng `rig seat continue <seat>` nếu README của lệnh `rig ps` gợi ý. Đừng bật quyền rộng chỉ để hết bị hỏi; chỉ làm vậy khi bạn hiểu mình đang cho phép điều gì.

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

**Điểm mạnh.** OpenRig giải quyết đúng nỗi đau của người dùng nhiều agent: mất dấu phiên, mất ngữ cảnh, không biết ai làm gì. Đội dựng sẵn giúp bạn có kết quả đầu tiên khá nhanh. Mã nguồn mở, giấy phép Apache-2.0, và repo vẫn được cập nhật trong vài tháng gần đây. Tác giả cũng viết hướng dẫn cài khá kỹ, có cả đường cài thử không thay đổi (`--dry-run`).

**Giới hạn.** Nó không dành cho người chưa từng dùng terminal. Nó đòi tmux, Node 22 hoặc 24, và một tài khoản Claude Code hoặc Codex. Windows chỉ chạy qua WSL2 và bộ kiểm thử tự động chưa chạy ở đó. Mặc định, operator có quyền rộng, và setup sửa nhiều file cấu hình trên máy. Chi phí dùng model vẫn là chi phí của tài khoản Claude Code hoặc Codex bạn đang có; mình chưa có thông tin về mức tiêu hao cụ thể.

**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 nhỏ, cứ dùng thẳng Claude Code hoặc Codex cho gọn. OpenRig đáng thử khi bạn thường xuyên chạy nhiều agent, muốn có người soát chéo và muốn công việc được ghi lại ở chỗ cố định. Bài này dựa trên phần đầu của README (phần còn lại đã bị cắt), nên trước khi dùng nghiêm túc, hãy đọc thêm mục "What OpenRig changes on your machine" trong repo.

## Câu hỏi thường gặp

### OpenRig có miễn phí không?

Bản thân OpenRig là phần mềm mã nguồn mở theo giấy phép Apache-2.0. Tuy vậy bạn cần một tài khoản Claude Code hoặc Codex đang dùng được; chi phí của các tài khoản đó nằm ngoài OpenRig và tư liệu chưa nêu cụ thể.

### Tôi dùng Windows thì chạy được không?

Được, nhưng qua WSL2. README nói Windows gốc (native) chưa được hỗ trợ. README cũng ghi bộ kiểm thử tự động của OpenRig chưa chạy trên WSL2, nên đây là đường đi còn mới.

### Cần cả Claude Code lẫn Codex không?

Không. Một nhà cung cấp là đủ để bắt đầu. Bạn có thể truyền `--providers claude` hoặc `--providers codex` khi chạy `rig setup`, và nhờ operator chỉnh đội `starter` cho khớp với thứ bạn có.

### OpenRig thay đổi gì trên máy tôi, có an toàn không?

Setup thêm 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 ~/.claude/skills và ~/.agents/skills. Operator mặc định có quyền rộng hơn đội dự án. README khuyên sao lưu các file này trước và có mục riêng liệt kê mọi thứ OpenRig ghi, nên bạn nên đọc mục đó trước khi cài.

### Cần GPU hay máy mạnh không?

Tư liệu chưa nói về yêu cầu phần cứng nào. Các yêu cầu được nêu chỉ gồm 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.

### Ba đội starter, workshop, factory khác nhau thế nào?

`starter` có một builder Claude Code và một reviewer Codex cho một thay đổi nhỏ. `workshop` có lead, builder, QA và reviewer cho công việc liên tục. `factory` có bảy agent cho sản phẩm làm dài hơi. Operator sẽ giúp bạn chọn đội phù hợp.

### Muốn bớt bị hỏi quyền liên tục thì sao?

README nhắc có bundle `workshop` cấp quyền rộng và chạy ở chế độ không ngắt quãng, nơi agent bỏ qua hộp thoại xin quyền. Vì quyền rộng, bạn nên đọc phần giải thích trước khi chọn.
