1. 從openrig這個名字說起它到底想解決什么問題第一次看到openrig這個詞我腦子里蹦出來的畫面是礦場里的鉆井平臺——rig 在英文里本來就有鉆井架、裝備架的意思。放到 AI 編程工具的語境里這個命名其實挺傳神它想做的就是給 Claude Code、Codex 這類命令行 AI 編程助手搭一個統(tǒng)一的裝備架讓你不用在多個工具、多個模型、多個終端會話之間來回折騰。先把結(jié)論擺在前面openrig不是一個模型也不是一個 IDE 插件它更像是一層編排與橋接層。從它關(guān)聯(lián)的熱詞就能看出端倪——Claude Code、Codex、Node.js、tmux這四個詞幾乎勾勒出了它的全部技術(shù)底座。Claude Code 和 Codex 是當(dāng)前最主流的兩類終端 AI 編程代理agentNode.js 是它們的運行時依賴tmux 則是讓這些長駐進程在后臺穩(wěn)定存活、隨時可切換的會話管理工具。openrig要做的就是把這幾樣?xùn)|西擰成一股繩。為什么這件事值得單獨做一個項目因為實際用過 Claude Code 或 Codex 的人都知道痛點非常具體。你裝完 Claude Code發(fā)現(xiàn)它默認(rèn)走官方訂閱想接本地模型比如 LM Studio 起的本地推理服務(wù)或者第三方 API就得改環(huán)境變量、改配置文件稍不留神就報cc switch local proxy failed while handling codex endpoint /responses這種讓人一頭霧水的錯。你裝完 Codex又發(fā)現(xiàn)它和 Claude Code 的配置格式、認(rèn)證方式、模型命名規(guī)則完全不一樣{detail:the gpt-5.6-sol model is not supported when using codex with a...}這類報錯能讓你排查半天。更別提還有codex is ignoring 1 unrecognized configuration setting這種配置寫了但沒生效的隱性坑。openrig的價值就在于它試圖把這些碎片化的配置、認(rèn)證、模型路由、會話管理統(tǒng)一到一個架子上。你不再需要為每個工具單獨記一套配置語法也不用擔(dān)心切換模型時把環(huán)境搞亂。對于同時用 Claude Code 和 Codex、又想在本地模型和云端模型之間靈活切換的開發(fā)者來說這就是剛需。這篇文章適合誰看三類人第一類是完全沒接觸過 Claude Code / Codex想從零搭一套能跑起來的環(huán)境的新手第二類是已經(jīng)裝了但被各種報錯和配置沖突折磨過的中級用戶第三類是想把 AI 編程代理集成進自己工作流、甚至想基于openrig思路做二次開發(fā)的老手。我會從環(huán)境準(zhǔn)備一路講到多工具協(xié)同、模型路由、會話?；畎巡冗^的坑和驗證過的方案都攤開講。提示本文涉及的所有工具均為本地開發(fā)輔助工具配置過程全部在你自己的機器上完成不涉及任何網(wǎng)絡(luò)代理相關(guān)內(nèi)容。所有模型接入均指通過官方或本地推理服務(wù)提供的標(biāo)準(zhǔn) API 接口。2. Node.js 運行時整個裝備架的地基怎么打2.1 為什么 Claude Code 和 Codex 都繞不開 Node.jsClaude Code 和 Codex CLI 本質(zhì)上都是 Node.js 寫的命令行程序通過 npm 全局安裝。這意味著你的 Node.js 版本直接決定了這兩個工具能不能裝、能不能跑。我見過太多人卡在第一步error installing 24.21.0: node.js v24.21.0 is not yet released or is not available——這個報錯的意思是你試圖安裝的 Node.js 版本號根本不存在或者你的包管理器源里還沒有這個版本。這里有個反直覺的點不是 Node.js 版本越新越好。Claude Code 和 Codex 對 Node.js 有明確的版本區(qū)間要求通常建議 LTS長期支持版本。截至我寫這篇內(nèi)容時Node.js 20.x 和 22.x 的 LTS 是最穩(wěn)妥的選擇。24.x 雖然新但很多 AI 工具的依賴鏈還沒完全適配貿(mào)然上最新版容易遇到原生模塊編譯失敗的問題。在 Ubuntu 上裝 Node.js我不推薦直接用apt install nodejs因為系統(tǒng)源里的版本往往偏舊。更可靠的做法是用 NodeSource 的源或者用 nvmNode Version Manager做版本管理。nvm 的好處是你可以同時裝多個版本隨時切換這對需要測試不同工具兼容性的人來說非常實用。# 安裝 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加載 shell 配置 source ~/.bashrc # 安裝 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 驗證 node -v npm -v裝完之后node -v應(yīng)該輸出v20.x.x。如果你在 Windows 上建議直接去 Node.js 官網(wǎng)下載 LTS 版本的安裝包安裝時勾選Add to PATH省去手動配環(huán)境變量的麻煩。Windows 下用 nvm-windows 也可以但體驗不如 Linux/macOS 順滑偶爾會遇到權(quán)限問題。2.2 npm 全局目錄與權(quán)限一個容易被忽略的坑Node.js 裝好了接下來裝 Claude Code 或 Codex 時很多人會遇到EACCES權(quán)限錯誤。這是因為 npm 默認(rèn)的全局安裝目錄需要 root 權(quán)限。有兩種解法一是每次都用sudo npm install -g但這會帶來后續(xù)權(quán)限混亂二是把 npm 的全局目錄改到用戶目錄下。# 創(chuàng)建用戶級全局目錄 mkdir -p ~/.npm-global # 配置 npm 使用該目錄 npm config set prefix ~/.npm-global # 把該目錄加入 PATH寫入 ~/.bashrc 或 ~/.zshrc export PATH~/.npm-global/bin:$PATH source ~/.bashrc這樣配完之后npm install -g就不需要 sudo 了后續(xù)升級工具也不會因為權(quán)限問題失敗。這個細(xì)節(jié)看起來小但它能幫你避開后面一連串莫名其妙的報錯。2.3 驗證運行時是否真的就緒裝完 Node.js 和 npm 之后別急著裝 AI 工具先做一輪基礎(chǔ)驗證。我習(xí)慣跑這幾個命令node -v # 確認(rèn)版本 npm -v # 確認(rèn) npm 可用 npm config get prefix # 確認(rèn)全局目錄 which node # 確認(rèn) node 路徑如果which node指向的是 nvm 管理的路徑比如~/.nvm/versions/node/v20.x.x/bin/node說明 nvm 生效正常。如果指向/usr/bin/node那可能是系統(tǒng)自帶的舊版本在干擾需要檢查 PATH 順序。注意如果你之前用 apt 裝過 nodejsnvm 和系統(tǒng)版本可能共存導(dǎo)致node -v和which node結(jié)果不一致。這種情況下建議sudo apt remove nodejs清理掉系統(tǒng)版本避免版本沖突。3. Claude Code 與 Codex 的安裝、認(rèn)證與首次跑通3.1 Claude Code 的安裝路徑與認(rèn)證方式Claude Code 通過 npm 全局安裝npm install -g anthropic-ai/claude-code裝完之后在終端輸入claude就能啟動。首次啟動會引導(dǎo)你完成認(rèn)證。這里有個關(guān)鍵分叉你是用官方訂閱還是接第三方 API / 本地模型如果你用官方訂閱直接按引導(dǎo)登錄即可。但如果你看到y(tǒng)our organization has disabled claude subscription access for claude code這個報錯說明你的賬號所屬組織關(guān)閉了 Claude Code 的訂閱訪問權(quán)限。這種情況下你需要走 API Key 的方式或者聯(lián)系組織管理員。接第三方 API 或本地模型時核心是配置環(huán)境變量。Claude Code 支持通過ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY來指定自定義端點。比如你想讓它調(diào)用 LM Studio 起的本地模型export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio claudeLM Studio 默認(rèn)在 1234 端口提供 OpenAI 兼容的 API。但要注意Claude Code 期望的是 Anthropic 格式的 API而 LM Studio 提供的是 OpenAI 格式兩者并不完全兼容。這就是為什么很多人接本地模型時會失敗——協(xié)議對不上。解決辦法是用一個轉(zhuǎn)換層比如 LiteLLM 之類的代理工具把 OpenAI 格式轉(zhuǎn)成 Anthropic 格式或者直接用支持 Anthropic 協(xié)議的本地推理服務(wù)。3.2 Codex 的安裝與它和 Claude Code 的差異Codex CLI 的安裝方式類似npm install -g openai/codex但 Codex 的配置體系和 Claude Code 完全不同。Codex 用~/.codex/config.toml或環(huán)境變量來配置認(rèn)證走 OpenAI 的 API Key 或登錄流程。常見的報錯codex登錄不上通常和網(wǎng)絡(luò)環(huán)境、API Key 有效性、或者組織設(shè)置有關(guān)。而codex無法加載組織設(shè)置則往往是因為你的賬號在組織里沒有對應(yīng)的權(quán)限配置。Codex 接第三方模型比如 DeepSeek時需要改config.toml里的model_provider和base_url。這里有個大坑Codex 對模型名稱有白名單校驗?zāi)銓懸粋€它不認(rèn)識的模型名就會報the gpt-5.6-sol model is not supported when using codex with a...。解決辦法是查 Codex 官方文檔支持的模型列表或者用它的model_providers自定義配置來繞過校驗。3.3 兩個工具的核心差異對照維度Claude CodeCodex CLI安裝包anthropic-ai/claude-codeopenai/codex配置文件環(huán)境變量為主~/.codex/config.tomlAPI 協(xié)議Anthropic 格式OpenAI 格式本地模型接入需協(xié)議轉(zhuǎn)換相對直接常見認(rèn)證報錯組織禁用訂閱登錄失敗、組織設(shè)置加載失敗模型名校驗較寬松較嚴(yán)格有白名單這張表是我實際用下來總結(jié)的不是官方文檔抄的。理解這些差異你才能在openrig這類編排層里正確地路由請求。3.4 首次跑通的驗證清單裝完兩個工具后別急著上復(fù)雜配置先各自跑一個最小驗證claude --version和codex --version確認(rèn)安裝成功在空目錄下啟動claude問一個簡單問題確認(rèn)能收到回復(fù)同樣啟動codex確認(rèn)基礎(chǔ)對話可用檢查各自的配置文件位置確認(rèn)沒有語法錯誤我踩過的一個坑是Claude Code 和 Codex 同時裝在全局目錄下某些共享依賴版本沖突導(dǎo)致其中一個啟動時報模塊找不到。解決辦法是給它們分別用獨立的 Node.js 版本nvm 切換或者確保全局依賴樹干凈。4. tmux 會話保活讓 AI 代理在后臺穩(wěn)定干活4.1 為什么 AI 編程代理需要 tmuxClaude Code 和 Codex 都是長駐進程一次任務(wù)可能跑幾分鐘甚至更久。如果你直接在 SSH 會話里跑網(wǎng)絡(luò)一斷進程就沒了之前的工作全白費。tmux 解決的就是這個問題它創(chuàng)建一個持久化的終端會話你斷開連接后會話繼續(xù)存在重新連上就能恢復(fù)。更重要的是openrig這類編排工具往往需要同時管理多個 AI 代理會話——一個跑 Claude Code 處理前端代碼一個跑 Codex 處理后端邏輯還有一個跑測試。用 tmux 可以給每個會話起個名字隨時切換互不干擾。# 創(chuàng)建名為 claude-work 的會話 tmux new -s claude-work # 在會話里啟動 Claude Code claude # 按 CtrlB 然后按 D 脫離會話進程繼續(xù)運行 # 重新連接 tmux attach -t claude-work # 列出所有會話 tmux ls4.2 tmux 配置里值得改的幾個默認(rèn)項tmux 默認(rèn)配置有幾個反人類的地方我建議在~/.tmux.conf里改掉# 把前綴鍵從 CtrlB 改成 CtrlA更順手 set -g prefix C-a unbind C-b bind C-a send-prefix # 開啟鼠標(biāo)支持可以點擊切換面板 set -g mouse on # 設(shè)置更大的回滾緩沖區(qū)AI 輸出很長默認(rèn) 2000 行不夠 set -g history-limit 50000 # 窗口編號從 1 開始 set -g base-index 1 setw -g pane-base-index 1history-limit這個特別重要。AI 代理的輸出動輒幾百行默認(rèn)緩沖區(qū)很快就被沖掉了你想往上翻看之前的輸出都翻不到。設(shè)成 50000 行之后基本夠用。4.3 用 tmux 編排多代理工作流假設(shè)你要同時跑 Claude Code 和 Codex可以這樣組織# 創(chuàng)建主會話 tmux new -s openrig -d # 在會話里創(chuàng)建第一個窗口跑 Claude Code tmux new-window -t openrig -n claude tmux send-keys -t openrig:claude claude C-m # 創(chuàng)建第二個窗口跑 Codex tmux new-window -t openrig -n codex tmux send-keys -t openrig:codex codex C-m # 創(chuàng)建第三個窗口跑日志監(jiān)控 tmux new-window -t openrig -n logs tmux send-keys -t openrig:logs tail -f ~/.openrig/logs/*.log C-m這樣你一個tmux attach -t openrig就能在三個窗口之間用CtrlA加數(shù)字切換。這套編排思路就是openrig想標(biāo)準(zhǔn)化的東西——把會話管理、進程啟動、日志監(jiān)控統(tǒng)一起來。提示tmux 會話在系統(tǒng)重啟后會丟失。如果你需要開機自動恢復(fù)可以配合 systemd 服務(wù)或者寫一個啟動腳本在登錄時自動重建會話。但要注意AI 代理的認(rèn)證狀態(tài)可能不會自動恢復(fù)需要重新登錄。5. 模型路由與配置沖突那些報錯背后的真實原因5.1cc switch local proxy failed到底在說什么這個報錯cc switch local proxy failed while handling codex endpoint /responses是很多人切換模型時遇到的。拆開看cc switch是切換配置的動作local proxy是本地代理層codex endpoint /responses是 Codex 的響應(yīng)接口。整句話的意思是切換配置時本地代理在處理 Codex 的/responses端點時失敗了。根因通常有三個第一代理層沒有正確識別 Codex 的 API 格式OpenAI 格式 vs Anthropic 格式第二切換后的模型端點不可達或返回了非預(yù)期格式第三配置文件里有殘留的舊配置和新配置沖突。排查順序我建議這樣先確認(rèn)目標(biāo)模型端點能獨立訪問用 curl 直接打再檢查代理層的日志看它把請求轉(zhuǎn)發(fā)到了哪里最后對比新舊配置文件的差異。很多時候問題就出在配置文件里同時存在兩套 provider 定義代理不知道該用哪個。5.2codex is ignoring 1 unrecognized configuration setting的隱性坑這個警告看起來無害但它意味著你寫的某個配置項 Codex 根本不認(rèn)識直接被忽略了。如果你以為這個配置生效了實際沒有后面就會遇到明明配了卻不工作的詭異現(xiàn)象。常見的 unrecognized setting 包括拼寫錯誤的鍵名比如model_provider寫成model_providers、版本不支持的配置項、放錯層級的配置。解決辦法是查 Codex 對應(yīng)版本的配置文檔逐項核對。我習(xí)慣把配置項分成確認(rèn)支持和待驗證兩類待驗證的先用最小配置測試確認(rèn)生效后再加進去。5.3 多工具共存時的配置隔離策略Claude Code 和 Codex 如果都接同一個第三方 API很容易出現(xiàn)配置互相干擾。我的做法是按工具隔離配置Claude Code 的配置放在獨立的 env 文件里啟動時 sourceCodex 的配置放在~/.codex/config.toml不和其他工具共享本地模型的路由配置單獨放一份用環(huán)境變量注入# ~/.openrig/env/claude.env export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlocal-key # ~/.openrig/env/codex.env export OPENAI_BASE_URLhttp://localhost:1234/v1 export OPENAI_API_KEYlocal-key啟動時按需 source 對應(yīng)的文件避免全局環(huán)境變量污染。這樣即使兩個工具同時跑也不會因為環(huán)境變量沖突而報錯。5.4 模型名稱校驗的繞過思路Codex 對模型名的白名單校驗是很多人的攔路虎。當(dāng)你用一個自定義模型名時它會直接拒絕。繞過思路有兩個一是用 Codex 支持的模型名做別名映射在代理層把請求里的模型名替換成真實模型名二是用model_providers自定義 provider聲明你自己的模型列表。第一種方案更通用因為它不依賴 Codex 的配置能力。你可以在本地起一個輕量代理收到 Codex 的請求后把model字段替換成實際模型名再轉(zhuǎn)發(fā)給真正的推理服務(wù)。這樣 Codex 以為自己在調(diào)官方模型實際調(diào)的是你的本地模型。6. 把 openrig 的思路落地成自己的工作流6.1 目錄結(jié)構(gòu)設(shè)計基于openrig的編排理念我建議這樣組織你的工作目錄~/.openrig/ ├── env/ # 各工具的環(huán)境變量文件 │ ├── claude.env │ └── codex.env ├── config/ # 工具配置文件 │ ├── codex-config.toml │ └── proxy-config.yaml ├── logs/ # 運行日志 ├── scripts/ # 啟動、切換、監(jiān)控腳本 │ ├── start-claude.sh │ ├── start-codex.sh │ └── switch-model.sh └── sessions/ # tmux 會話狀態(tài)記錄這個結(jié)構(gòu)的好處是配置、日志、腳本分離出問題時能快速定位。切換模型時只改env/下的文件不影響其他部分。6.2 一鍵啟動腳本#!/bin/bash # ~/.openrig/scripts/start-claude.sh # 加載環(huán)境變量 source ~/.openrig/env/claude.env # 檢查 tmux 會話是否已存在 if tmux has-session -t claude-work 2/dev/null; then echo 會話已存在正在連接... tmux attach -t claude-work else echo 創(chuàng)建新會話... tmux new -s claude-work -d tmux send-keys -t claude-work claude C-m tmux attach -t claude-work fi這個腳本做了兩件事檢查會話是否存在存在就連接不存在就創(chuàng)建。這樣你無論什么時候執(zhí)行結(jié)果都是進入一個可用的 Claude Code 會話。6.3 模型切換的原子化操作切換模型最容易出問題的地方是改了一半。比如你改了環(huán)境變量但沒重啟進程或者改了配置文件但代理沒重載。原子化操作的意思是要么全部生效要么全部不生效。#!/bin/bash # ~/.openrig/scripts/switch-model.sh MODEL$1 ENV_FILE~/.openrig/env/claude.env # 備份當(dāng)前配置 cp $ENV_FILE ${ENV_FILE}.bak # 寫入新配置 sed -i s|ANTHROPIC_BASE_URL.*|ANTHROPIC_BASE_URL\$MODEL\| $ENV_FILE # 驗證新端點可達 if ! curl -s --max-time 5 $MODEL/health /dev/null; then echo 新端點不可達回滾配置 mv ${ENV_FILE}.bak $ENV_FILE exit 1 fi # 重啟會話 tmux kill-session -t claude-work 2/dev/null source $ENV_FILE tmux new -s claude-work -d tmux send-keys -t claude-work claude C-m echo 切換完成已重啟會話這個腳本的關(guān)鍵是先驗證再切換端點不可達就回滾避免把環(huán)境搞壞。6.4 日志與可觀測性AI 代理跑起來之后你需要知道它在干什么。我建議至少記錄三類日志啟動日志記錄用了哪個配置、哪個模型、請求日志記錄每次 API 調(diào)用的耗時和狀態(tài)、錯誤日志記錄所有非 200 響應(yīng)。# 在啟動腳本里加日志重定向 tmux send-keys -t claude-work claude 21 | tee -a ~/.openrig/logs/claude-$(date %Y%m%d).log C-m這樣每個會話的輸出都會同時顯示在終端和寫入日志文件。出問題時翻日志比憑記憶排查快得多。7. 我踩過的幾個真實坑和對應(yīng)的解法7.1 版本不匹配導(dǎo)致的裝上了但跑不起來有一次我?guī)团笥雅洵h(huán)境Node.js 裝的是 24.xClaude Code 裝上了但一啟動就報原生模塊加載失敗。折騰了半天才發(fā)現(xiàn)是 Node.js 版本太新某個依賴還沒適配。降到 20 LTS 之后立刻正常。這個教訓(xùn)是AI 工具鏈對 Node.js 版本敏感別盲目追新LTS 才是穩(wěn)妥選擇。7.2 環(huán)境變量污染導(dǎo)致的配置不生效我習(xí)慣在~/.bashrc里 export 一堆環(huán)境變量結(jié)果 Claude Code 和 Codex 同時讀到了對方的配置行為變得詭異。后來改成按需 source 獨立 env 文件問題消失。如果你也遇到明明配了卻不生效先檢查env | grep -i api看看有沒有多余的環(huán)境變量在干擾。7.3 tmux 會話里的認(rèn)證狀態(tài)丟失tmux 會話?；詈芎糜玫袀€坑如果你在會話里完成了 Claude Code 的登錄然后系統(tǒng)重啟tmux 會話沒了重新創(chuàng)建會話后需要重新登錄。認(rèn)證 token 通常存在~/.claude/或類似目錄下只要這個目錄沒被清理重新登錄時可能自動恢復(fù)。但如果 token 過期了還是得手動重新認(rèn)證。我的做法是把認(rèn)證相關(guān)的目錄加入備份避免重裝系統(tǒng)后重新配置。7.4 本地模型接入時的協(xié)議不兼容前面提過Claude Code 要 Anthropic 格式LM Studio 給的是 OpenAI 格式。我試過直接用報了一堆格式錯誤。后來用一個輕量轉(zhuǎn)換層把 OpenAI 格式轉(zhuǎn)成 Anthropic 格式才跑通。如果你不想自己寫轉(zhuǎn)換層可以找現(xiàn)成的開源代理工具配置好映射規(guī)則即可。核心是要理解協(xié)議轉(zhuǎn)換的關(guān)鍵是請求體和響應(yīng)體的字段映射尤其是messages、model、max_tokens這幾個字段。8. 關(guān)于 openrig 這類編排思路的延伸想法openrig目前還是個相對早期的概念但它的方向很明確隨著 AI 編程代理越來越多Claude Code、Codex未來還會有更多開發(fā)者需要一個統(tǒng)一的編排層來管理它們。這個編排層要解決的核心問題包括配置統(tǒng)一、模型路由、會話?；?、日志聚合、成本追蹤。我自己在實際使用中的體會是與其等一個完美的工具出現(xiàn)不如先用手頭的 tmux 腳本 環(huán)境變量隔離把工作流搭起來。這套土辦法雖然不優(yōu)雅但足夠可靠而且你完全掌控每個環(huán)節(jié)。等openrig這類工具成熟了再遷移過去也不遲。最后分享一個小技巧給每個 AI 代理會話起一個有意義的名字比如claude-frontend、codex-backend、test-runner而不是默認(rèn)的0、1、2。這樣tmux ls的時候一眼就能看出哪個會話在干什么切換的時候也不用猜。這個習(xí)慣幫我省了不少時間尤其是在同時跑四五個會話的時候。