【2026 最新】OpenRig 教學：兩席首跑、Hooks 盤點與卡住復原

你想讓兩個 Codex 分工：一個修改專案，另一個檢查，但不想在一排終端機視窗裡猜「誰做完了」。這篇 OpenRig 教學從官方 first-project 的兩個座位出發，教你看安裝會改什麼、如何送出第一張小任務，以及卡住時怎麼查證與復原。

這篇寫給會開終端機、但第一次管理多個程式 Agent 的讀者。你可以照步驟在自己的小型 Git 專案操作；每一步都有「看到什麼才算過關」。操作步驟依 OpenRig 0.6.0 文件整理；文中的故障案例都附上回報版本與環境，供你練習辨認訊號。

先說結論：OpenRig 是座位、任務佇列和驗收收據

OpenRig ＝固定座位（誰負責）＋任務佇列（現在欠什麼）＋驗收收據（候選成果有沒有被檢查）。把它想成小型工作室：dev-owner@first-project 接單與交付，dev-check@first-project 核對同一份候選成果，而你仍是決定是否採用的人。OpenRig 是本機協調層，底下仍由你已登入的 Codex 執行工作；它不會讓模型的回答自動變成正確程式。

這個起步範例適合「在一個 repo 做一件可驗收的小改動」。如果你還不熟悉 Agent 外圍執行層，可先看 Agent Harness 是什麼；想了解手動設計協作流程，接著讀 Opus 與 Codex 的任務交接。以下專注 OpenRig 本身。

OpenRig 教學第一關：版本、登入與設定寫入

先核對版本，再談安裝。OpenRig 0.6.0 發布說明寫明支援 Node.js 22 或 24；Apple silicon Mac 建議 Node 22。較舊網頁仍可能列出 Node 20，這次首跑請以你實際安裝的版本和其 release notes 為準。官方 first-project 需要 tmux 與已登入的 Codex，這條兩席路徑不需要先登入 Claude Code。

• 在準備啟動的同一個終端機，依序查看 node --version、tmux -V、codex --version、codex login status。登入狀態不對時，先用 codex login 完成登入；Codex 官方登入文件也列出這兩個命令。
• 在乾淨的小型 Git repo 開始，先記下 git status --short。若已有未提交變更，先辨認哪些是自己的工作，之後才看得出 Agent 改了什麼。
• 安裝 CLI：npm install -g @openrig/cli，再看 rig --version。接著執行 rig setup --dry-run，讀完它打算處理的項目；若要套用整套機器設定，再執行 rig setup。對這個 starter，tmux、Codex 與登入狀態是你要逐項確認的條件。

為什麼要先備份？官方寫入清單指出，rig setup 會處理 ~/.tmux.conf；daemon 啟動可寫入 ~/.openrig、~/.codex/config.toml 與 provider hooks，啟動座位還可能寫工作區信任記錄與檔案。若你會用 Claude 座位，另要留意 ~/.claude.json、專案 .claude/settings.local.json 等。先在你自己的私人備份位置保存原檔與檔案權限，記錄哪些檔案原本不存在；不要把含登入資訊的備份放進 Git repo 或貼到 issue。

--dry-run 只展示 rig setup 的計畫，不涵蓋之後 daemon 啟動、hooks 與 workspace trust 的所有寫入。所以首跑前還要讀上面的官方清單，並選擇保留提示、記住少數命令，或調整座位權限。預設 starter 用 Codex 的 workspace-write sandbox，審批仍取決於原生 Codex 設定；初學者可先保留提示，看到具體命令再決定。

Hooks 檢查：看設定檔的前後差異

首次啟動 daemon 與座位後，拿首跑前的私人備份和目前的 ~/.codex/config.toml 比對：diff -u <你的備份檔路徑> ~/.codex/config.toml。重點是辨認 OpenRig 新增的活動 relay hook、信任記錄，以及原有設定是否被改動；diff 顯示差異時回傳非零是正常的。若原檔不存在，直接記錄它是新建檔案。把差異當作回復時的清單，別整份覆蓋後來由其他工具更新的設定。對於沒有出現的項目，先檢查實際版本與 rig doctor --json，再判斷是否是設定關閉或啟動階段尚未到達。

OpenRig 教學第二關：兩席首跑與一張可驗收的任務卡

在小型 repo 執行 rig specs preview first-project，確認範例確實是 owner 與 checker 兩個 Codex 座位。接著跑 rig up first-project --cwd . --plan：這是啟動前的專案與工作目錄預覽。讀清楚計畫後，再執行 rig up first-project --cwd .。此時 rig status 看整體，rig ps --nodes --rig first-project 看兩張座位；兩者各回答不同問題。

例如選一個「缺欄位時顯示欄位名稱、舊資料保持不變」的 CSV 匯入錯誤處理。要求要包含改動邊界、測試方法、checker 要核對的同一份候選成果、交付後如何試用。可把下面的單行指令當模板，將任務文字改成你 repo 真正存在的功能：

rig send dev-owner@first-project '改善 CSV 匯入缺少必填欄位時的錯誤：指出欄位名稱，舊資料保持不變。請記錄任務 ID、加入回歸測試、讓 dev-check 檢查同一份候選成果，回報結果與本機試用方式；保持在本機，不要發布。'

這一步的「送達」只代表 owner 收到訊息，不等於佇列裡已有任務，更不等於驗收通過。在旁觀終端機查 rig queue list --destination dev-owner@first-project --limit 1000 與 checker 的同型命令；拿到 ID 後用 rig queue show <id> --full、rig queue transitions <id> 看承諾與狀態變化。最後親自讀 diff、執行專案原有測試、試一次缺欄位輸入，再對照 checker 評的是哪一版。若你想把這套收據習慣搬到其他工具，可讀 合併前的 Agent 意圖衝突檢查。

把「完成」拆成可以逐張核對的收據

假設 owner 回你「已修好」。第一張收據是任務 ID：它讓你查到這件事由誰承接、目前卡在哪個狀態。第二張是候選成果：你在 git diff 看見缺欄位時的處理與新增測試，確認改動沒有順手重寫其他匯入流程。第三張是 checker 的回覆：它應說明檢查了哪一份候選檔案、跑了哪個測試、發現或沒有發現什麼。最後你親自匯入一份缺欄位的範例，核對錯誤訊息點名那個欄位，原本資料仍可讀。只有「完成了」三個字，缺少讓下一個人重看結果的路徑。

若測試失敗，先保留失敗輸出與對應的候選版本，讓 owner 修同一張任務卡；checker 下一輪也應明確指出新舊候選差異。這樣重試是在累積證據，不是重新開一場沒人記得前因的對話。若你的 repo 沒有 CSV 匯入，就把案例換成一個同樣能手動觸發、且有現成測試入口的小錯誤。

卡住怎麼查：座位提示、額度與復原收據

先看座位，再看總覽。截至 2026 年 9 月 29 日，OpenRig 的 issue #81 記錄了一個 0.5.16、六席 Claude Code 環境：某座位在權限提示等約 1.5 小時，座位列顯示 needs_input，rig 總覽卻顯示 ATTN 0。維護者解釋兩個畫面當時取用不同訊號。這是有版本與環境範圍的個案，不能推論你的 0.6.0 兩席 Codex 一定會重演；可執行的教訓是：定期看 rig ps --nodes --rig first-project，碰到提示就回到該座位的終端機確認。

不要把「對話停住」直接當成模型失敗。先寫下時間、rig --version、座位地址、rig status、rig ps --nodes --rig first-project 的狀態，以及相關 queue ID 與最新 transition。若是權限或信任提示，對照實際命令與你選的權限範圍，再在同一個座位處理；若 CLI 顯示 timeout，先重新讀狀態與收據，避免把已生效的操作再送一次。必要時用 rig doctor --json 取得健康診斷，並保留輸出供自己比對。

issue #86 記錄 0.5.17 的十一席復原：部分 Claude 座位實際在工作，卻保留 attention_required；回報者也補充 Codex 座位的相關觀察。這表示「需要你注意」也要和 pane、活動、佇列進度互相核對。官方 復原指引建議：關掉觀看視窗可用 rig tui --shared 回原畫面；daemon 重啟後重讀 rig status 與既有佇列；主機重開後從既有 rig 與座位恢復，先看保留的工作，再決定是否開新對話。不要為了消除一個警示，就在不清楚原任務責任時另起座位。

若以後改用混合 Claude Code 座位，要另外檢查用量訊號。issue #99 的回報與維護者回覆指出，截至 9 月 28 日，0.5.17／當時 main 的 Claude 用量上限偵測路徑有缺口；這不是 first-project 兩個 Codex 座位的實測結果。看到座位長時間無進展時，先看原生 harness 顯示的狀態和 queue，記下卡點，而非只憑 OpenRig 總覽推測額度已自動復原。

何時停下、還原，或改用混合 conveyor？

完成一張任務卡後，先保存 diff、測試輸出、checker 結果與 queue ID，再決定是否保留這個團隊。官方提供 rig down --snapshot 來保存拓樸，再用 rig up <name> 依快照恢復；快照是 OpenRig 拓樸與狀態的收據，不是你 Git 專案的備份。關閉 TUI 觀看視窗也不等於停掉座位。若要回復設定，先停止相關 OpenRig 程序，對照首跑前的備份與目前檔案，逐項還原你能辨識的 OpenRig 寫入；不要直接用舊檔覆蓋已由其他工具更新的設定。

當兩席已穩定交付、你真的需要「需求整理→規劃→實作→檢查」四段接力，再預覽 rig specs preview conveyor --kind rig。官方 conveyor 是 Claude Code 與 Codex 混合的四席範例；先盤點兩邊登入、權限與用量，以及 handoff 要留下什麼證據。若只是想試一個小功能，兩席比較容易辨認到底是哪一步卡住。更多關於工作區隔離，可接著看 Agent Workspace 和 動手建立 Agent Harness。

OpenRig 教學常見問題

1. 只想跑兩席，必須先登入 Claude Code 嗎？

這個 starter 的 repo 任務重點是 tmux 和已登入的 Codex。先確認 codex login status；rig setup 可能同時檢查其他可選元件，請分項看結果。

2. rig setup --dry-run 看過就完成副作用盤點了嗎？

還要讀啟動時的寫入清單。它預覽 setup 計畫；daemon、provider hooks、信任設定在後續階段處理。備份清單應涵蓋你實際會用的 provider。

3. rig up --plan 已經啟動 Agent 了嗎？

這是啟動前預覽。檢查目錄與規格後，才執行 rig up first-project --cwd .，再看座位 readiness。

4. rig send 回應成功就是工作完成嗎？

不是。它只證明訊息送達；用 queue ID、transition、檔案 diff、測試與 checker 對照同一份候選成果。

5. 總覽顯示 ATTN 0，就可以不用看座位嗎？

請仍看座位。issue #81 的 0.5.16 個案出現總覽與座位不一致；你的版本要以實際座位、pane 與佇列證據判斷。

6. 顯示 attention_required 就一定代表座位停工嗎？

不一定。issue #86 回報 0.5.17 復原警示與座位實際活動不一致；先核對 pane、活動與 queue transition，別盲目重啟。

7. 關掉 TUI 是停止 Agent 嗎？

不是同一件事。官方區分觀看終端機與團隊座位；要回畫面可用 rig tui --shared，要停團隊則先看 rig down --snapshot 的用途。

8. 什麼時候升到 conveyor？

兩席任務已能穩定留下驗收收據，且四段 handoff 真有必要時。先預覽規格，逐項確認兩種 harness 的登入與權限；別用座位數代替任務品質。

給新手的三個驗收重點

• 開跑前：核對 0.6.0 的 Node 條件、tmux、Codex 登入；讀兩份計畫與設定寫入清單。
• 執行中：盯兩張座位與 queue ID；權限提示、timeout 和用量問題都要留下狀態收據。
• 交付時：自己讀 diff、跑測試、對照 checker 的候選版本，再決定是否採用或擴成更多座位。