1. openrig 到底是個什么東西第一次看到 openrig 這個名字很多人會以為是某個硬件外設(shè)或者開源機械臂項目。實際上結(jié)合它周邊的關(guān)鍵詞——Claude Code、Codex、YAML、Node.js——可以很清楚地判斷出openrig 是一個圍繞 AI 編程助手生態(tài)構(gòu)建的本地配置與代理編排工具。它的核心價值在于把 Claude Code、Codex 這類命令行 AI 編程工具的運行環(huán)境、模型接入、代理轉(zhuǎn)發(fā)、配置管理統(tǒng)一到一個可維護的框架里。說白了你平時用 Claude Code 寫代碼可能遇到幾個煩人的問題公司網(wǎng)絡(luò)環(huán)境需要走本地代理、想切換到 DeepSeek 或 GLM 這類第三方模型、多個項目需要不同的配置、每次換機器都要重新折騰一遍環(huán)境。openrig 就是來解決這些問題的。它用 YAML 做配置描述用 Node.js 做運行時把 Claude Code 和 Codex 的啟動參數(shù)、環(huán)境變量、代理規(guī)則、模型映射全部收攏到一份配置文件里。這篇文章適合誰看如果你是剛接觸 Claude Code 或 Codex 的新手想搞清楚怎么在本地把環(huán)境跑通如果你已經(jīng)在用這些工具但每次配置都靠手動改環(huán)境變量、記不住參數(shù)如果你需要在多個模型供應(yīng)商之間切換比如今天用 Claude 官方、明天接 DeepSeek、后天試 GLM——那 openrig 這套思路值得你花時間研究。我自己的使用場景是這樣的手頭有三臺開發(fā)機一臺 macOS 日常開發(fā)一臺 Ubuntu 跑 CI 和長任務(wù)還有一臺 Windows 偶爾做前端調(diào)試。以前每臺機器上 Claude Code 的配置都是散的環(huán)境變量寫在 shell 配置文件里代理設(shè)置靠手動 export換模型要改好幾個地方。后來用 openrig 的思路把配置統(tǒng)一成 YAML 之后同步配置就是復(fù)制一個文件的事。注意openrig 本身不是一個官方項目它更像是一種配置管理模式的代稱。你在 GitHub 上搜到的同名倉庫可能和本文描述的不完全一致但核心思路是通用的——用結(jié)構(gòu)化配置管理 AI 編程工具的運行時環(huán)境。2. 核心組件拆解YAML、Node.js 與代理層2.1 為什么選 YAML 做配置載體YAML 在這套體系里扮演的是“唯一真相源”的角色。你可能會問為什么不用 JSON 或者 TOMLJSON 的問題是寫注釋不方便而配置文件恰恰最需要注釋——你得記清楚每個參數(shù)是干什么的。TOML 雖然可讀性好但嵌套結(jié)構(gòu)表達起來比較啰嗦。YAML 在可讀性和表達力之間取得了不錯的平衡支持錨點和引用這對多環(huán)境配置復(fù)用非常關(guān)鍵。一個典型的 openrig 配置結(jié)構(gòu)大概長這樣# openrig.yaml version: 1.0 defaults: provider: anthropic proxy: enabled: true host: 127.0.0.1 port: 7890 providers: anthropic: base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY models: - claude-sonnet-4-20250514 - claude-opus-4-20250514 deepseek: base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat - deepseek-coder glm: base_url: https://open.bigmodel.cn/api/paas/v4 api_key_env: GLM_API_KEY models: - glm-4-plus profiles: work: provider: anthropic proxy: enabled: true personal: provider: deepseek proxy: enabled: false這份配置里providers定義了各個模型供應(yīng)商的接入信息profiles定義了不同使用場景的組合。你切換工作環(huán)境只需要改defaults.provider或者指定 profile不用去動環(huán)境變量。YAML 的錨點功能在這里特別有用。比如你有多個 provider 共享相同的代理設(shè)置可以這樣寫_proxy_default: proxy_default enabled: true host: 127.0.0.1 port: 7890 providers: anthropic: proxy: *proxy_default openai: proxy: *proxy_default這樣改一處就能影響所有引用它的地方避免了復(fù)制粘貼帶來的不一致。2.2 Node.js 在其中的角色Node.js 是 openrig 的運行時基礎(chǔ)。為什么不用 Python 或者 Go因為 Claude Code 和 Codex 本身就是 Node.js 生態(tài)的工具用 npm 全局安裝的。openrig 作為它們的配置管理層用 Node.js 寫可以無縫調(diào)用這些工具的 API也能直接復(fù)用 npm 的包管理機制。Node.js 的版本選擇有個坑要注意。Claude Code 對 Node.js 版本有要求一般建議用 LTS 版本。我實測下來Node.js 20.x 和 22.x 都能正常工作但 18.x 在某些新特性上會報錯。如果你看到類似error installing 24.21.0: node.js v24.21.0 is not yet released這種報錯說明你指定的版本號根本不存在去 Node.js 官網(wǎng)下載頁面確認一下當前 LTS 版本號。安裝 Node.js 最省事的方式是用版本管理器。macOS 和 Linux 上可以用 nvmWindows 上可以用 nvm-windows 或者直接下安裝包。用 nvm 的好處是可以在不同項目間切換 Node.js 版本# 安裝 nvm 后 nvm install 22 nvm use 22 nvm alias default 22 # 驗證 node -v npm -vopenrig 的啟動腳本通常是一個 Node.js 腳本它讀取 YAML 配置解析出當前 profile 對應(yīng)的環(huán)境變量然后以正確的參數(shù)啟動 Claude Code 或 Codex。這個腳本的核心邏輯大概是const fs require(fs); const yaml require(js-yaml); const { spawn } require(child_process); function loadConfig(path) { const raw fs.readFileSync(path, utf8); return yaml.load(raw); } function buildEnv(config, profileName) { const profile config.profiles[profileName]; const provider config.providers[profile.provider]; const env { ...process.env }; env.OPENRIG_PROVIDER profile.provider; env.OPENRIG_BASE_URL provider.base_url; env.OPENRIG_API_KEY process.env[provider.api_key_env]; if (profile.proxy profile.proxy.enabled) { env.HTTP_PROXY http://${profile.proxy.host}:${profile.proxy.port}; env.HTTPS_PROXY env.HTTP_PROXY; } return env; } const config loadConfig(./openrig.yaml); const env buildEnv(config, process.argv[2] || default); const child spawn(claude, process.argv.slice(3), { env, stdio: inherit });這段代碼的邏輯很直白讀配置、拼環(huán)境變量、啟動子進程。但就是這種直白的設(shè)計解決了很多手動配置時的痛點。2.3 代理層的設(shè)計考量代理層是 openrig 里最容易被忽視但最關(guān)鍵的部分。Claude Code 和 Codex 都需要訪問外部 API而在某些網(wǎng)絡(luò)環(huán)境下直接連接可能不穩(wěn)定或者根本連不上。這時候就需要一個本地代理來轉(zhuǎn)發(fā)請求。代理層的設(shè)計有幾個要點第一代理只對 AI 工具的流量生效不影響系統(tǒng)全局。你肯定不希望開個代理把整個系統(tǒng)的網(wǎng)絡(luò)都繞一遍。openrig 的做法是通過環(huán)境變量HTTP_PROXY和HTTPS_PROXY只注入到子進程父進程和其他程序不受影響。第二代理要支持按 provider 區(qū)分。有些 provider 需要走代理有些不需要。比如你接 DeepSeek 的國內(nèi)節(jié)點可能直連就很快走代理反而慢。配置里每個 provider 可以單獨設(shè)置代理開關(guān)。第三代理失敗要有降級策略。我遇到過代理進程掛了但 Claude Code 還在跑的情況請求全部超時。后來在 openrig 的啟動腳本里加了一個健康檢查啟動前先探測代理端口是否可達不可達就自動禁用代理并給出警告。const net require(net); function checkProxy(host, port, timeout 2000) { return new Promise((resolve) { const socket new net.Socket(); socket.setTimeout(timeout); socket.on(connect, () { socket.destroy(); resolve(true); }); socket.on(timeout, () { socket.destroy(); resolve(false); }); socket.on(error, () { resolve(false); }); socket.connect(port, host); }); }這個健康檢查邏輯很簡單但能避免很多“為什么請求一直卡住”的困惑。3. 從零搭建 openrig 工作流的完整實操3.1 環(huán)境準備與依賴安裝開始之前確認你手頭有這些東西一臺能正常上網(wǎng)的開發(fā)機、Node.js 環(huán)境、至少一個 AI 模型供應(yīng)商的 API Key。如果你還沒有 API Key先去對應(yīng)平臺注冊申請這里不展開。第一步安裝 Node.js。去 Node.js 官網(wǎng)下載 LTS 版本或者用包管理器# macOS with Homebrew brew install node22 # Ubuntu/Debian curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs # Windows # 直接去官網(wǎng)下載 .msi 安裝包雙擊安裝安裝完成后驗證node -v # 應(yīng)該輸出 v22.x.x npm -v # 應(yīng)該輸出 10.x.x第二步安裝 Claude Code 和 Codex。這兩個工具都是 npm 全局包npm install -g anthropic-ai/claude-code npm install -g openai/codex如果你在安裝 Claude Code 時遇到y(tǒng)our organization has disabled claude subscription access for claude code這類提示說明你的賬號類型不支持直接使用需要檢查訂閱狀態(tài)或者改用 API Key 方式接入。第三步創(chuàng)建工作目錄和配置文件mkdir -p ~/openrig cd ~/openrig npm init -y npm install js-yaml然后把前面提到的openrig.yaml配置文件放進去根據(jù)你自己的 provider 信息修改。3.2 配置文件編寫與參數(shù)詳解配置文件是 openrig 的核心值得花時間仔細寫。我把自己用的配置拆解一下每個參數(shù)都解釋清楚。version: 1.0 # 全局默認值所有 profile 繼承這里 defaults: provider: anthropic log_level: info timeout: 120000 # 代理設(shè)置可以被 profile 覆蓋 proxy: enabled: false host: 127.0.0.1 port: 7890 # 不走代理的地址列表 no_proxy: - localhost - 127.0.0.1 - *.local # 模型供應(yīng)商定義 providers: anthropic: base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY # 請求頭額外字段 headers: anthropic-version: 2023-06-01 models: - id: claude-sonnet-4-20250514 alias: sonnet - id: claude-opus-4-20250514 alias: opus deepseek: base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - id: deepseek-chat alias: ds-chat - id: deepseek-coder alias: ds-coder glm: base_url: https://open.bigmodel.cn/api/paas/v4 api_key_env: GLM_API_KEY models: - id: glm-4-plus alias: glm4 # 使用場景配置 profiles: # 日常開發(fā)用 Claude 官方 dev: provider: anthropic model: sonnet proxy: enabled: true # 寫代碼專用用 DeepSeek Coder code: provider: deepseek model: ds-coder proxy: enabled: false # 省錢模式用 GLM budget: provider: glm model: glm4 proxy: enabled: false幾個關(guān)鍵參數(shù)說明api_key_env指定的是環(huán)境變量名不是 API Key 本身。這樣做的好處是配置文件可以安全地提交到 Git不會泄露密鑰。你只需要在 shell 里 export 對應(yīng)的環(huán)境變量就行。models里的alias是給模型起短名方便在命令行里快速指定。比如openrig dev --model opus比openrig dev --model claude-opus-4-20250514好記多了。no_proxy列表里的地址不會走代理。這個在本地開發(fā)時特別有用比如你本地跑了一個模型服務(wù)肯定不希望請求繞一圈代理再回來。3.3 啟動腳本與命令行封裝配置文件寫好了接下來需要一個啟動腳本來讀取配置并啟動 Claude Code 或 Codex。我寫了一個比較完整的版本放在~/openrig/bin/openrig.js#!/usr/bin/env node const fs require(fs); const path require(path); const yaml require(js-yaml); const { spawn } require(child_process); const net require(net); const CONFIG_PATH path.join(__dirname, .., openrig.yaml); function loadConfig() { if (!fs.existsSync(CONFIG_PATH)) { console.error(配置文件不存在: ${CONFIG_PATH}); process.exit(1); } return yaml.load(fs.readFileSync(CONFIG_PATH, utf8)); } function checkPort(host, port, timeout 1500) { return new Promise((resolve) { const socket new net.Socket(); socket.setTimeout(timeout); socket.on(connect, () { socket.destroy(); resolve(true); }); socket.on(timeout, () { socket.destroy(); resolve(false); }); socket.on(error, () resolve(false)); socket.connect(port, host); }); } async function buildEnv(config, profileName) { const profile config.profiles[profileName]; if (!profile) { console.error(Profile ${profileName} 不存在); console.error(可用: ${Object.keys(config.profiles).join(, )}); process.exit(1); } const provider config.providers[profile.provider]; const env { ...process.env }; // 注入 provider 信息 env.OPENRIG_PROVIDER profile.provider; env.OPENRIG_BASE_URL provider.base_url; env.OPENRIG_MODEL profile.model || provider.models[0].id; // 注入 API Key const apiKey process.env[provider.api_key_env]; if (!apiKey) { console.warn(警告: 環(huán)境變量 ${provider.api_key_env} 未設(shè)置); } else { env.OPENRIG_API_KEY apiKey; } // 代理配置 const proxyConf { ...config.proxy, ...(profile.proxy || {}) }; if (proxyConf.enabled) { const alive await checkPort(proxyConf.host, proxyConf.port); if (alive) { const proxyUrl http://${proxyConf.host}:${proxyConf.port}; env.HTTP_PROXY proxyUrl; env.HTTPS_PROXY proxyUrl; env.NO_PROXY (proxyConf.no_proxy || []).join(,); console.log(代理已啟用: ${proxyUrl}); } else { console.warn(代理 ${proxyConf.host}:${proxyConf.port} 不可達已跳過); } } return env; } async function main() { const args process.argv.slice(2); const profileName args[0] || dev; const restArgs args.slice(1); const config loadConfig(); const env await buildEnv(config, profileName); // 決定啟動哪個工具 const tool env.OPENRIG_PROVIDER openai ? codex : claude; console.log(啟動 ${tool} [profile${profileName}, provider${env.OPENRIG_PROVIDER}]); const child spawn(tool, restArgs, { env, stdio: inherit, shell: process.platform win32 }); child.on(exit, (code) process.exit(code)); } main().catch((err) { console.error(err.message); process.exit(1); });給腳本加執(zhí)行權(quán)限并創(chuàng)建軟鏈接chmod x ~/openrig/bin/openrig.js sudo ln -s ~/openrig/bin/openrig.js /usr/local/bin/openrig現(xiàn)在你可以這樣用了# 用 dev profile 啟動 Claude Code openrig dev # 用 code profile 啟動并傳遞額外參數(shù) openrig code --resume # 查看當前配置 openrig dev --help3.4 多環(huán)境同步與版本管理配置寫好后怎么在多臺機器之間同步我的做法是把~/openrig目錄做成一個 Git 倉庫但 API Key 不放在配置文件里而是通過環(huán)境變量注入。每臺機器上單獨設(shè)置環(huán)境變量# 加到 ~/.bashrc 或 ~/.zshrc export ANTHROPIC_API_KEYsk-ant-xxxx export DEEPSEEK_API_KEYsk-xxxx export GLM_API_KEYxxxx這樣 Git 倉庫里只有配置結(jié)構(gòu)沒有敏感信息。換機器的時候 clone 下來設(shè)置好環(huán)境變量就能用。如果你不想把配置提交到遠程倉庫也可以用 rsync 或者 Syncthing 在本地網(wǎng)絡(luò)同步。我試過用 Syncthing 同步~/openrig目錄效果不錯改一臺機器上的配置其他機器幾秒鐘后就更新了。提示環(huán)境變量里的 API Key 在某些 shell 下可能被其他程序讀取到。如果你對安全性要求高可以用pass或者系統(tǒng)鑰匙串來管理密鑰然后在啟動腳本里動態(tài)讀取。4. 常見問題排查與避坑指南4.1 Claude Code 與 Codex 的典型報錯處理在實際使用中我踩過的坑主要集中在幾個方面。下面整理成速查表方便對照排查。報錯信息可能原因解決方法your organization has disabled claude subscription access賬號訂閱類型不支持改用 API Key 方式或檢查訂閱狀態(tài)cc switch local proxy failed while handling codex endpoint /responses代理轉(zhuǎn)發(fā)規(guī)則不匹配檢查代理配置確認/responses路徑被正確轉(zhuǎn)發(fā)the gpt-5.6-sol model is not supported模型名稱錯誤或未授權(quán)確認模型 ID 拼寫檢查 API Key 權(quán)限error installing 24.21.0: node.js v24.21.0 is not yet releasedNode.js 版本號不存在去官網(wǎng)確認當前 LTS 版本號codex無法加載組織設(shè)置配置文件路徑或權(quán)限問題檢查~/.codex/config.yaml是否存在且可讀請求一直超時無響應(yīng)代理不可達或網(wǎng)絡(luò)問題用curl測試代理端口檢查NO_PROXY設(shè)置關(guān)于cc switch local proxy failed這個報錯我專門研究過。它的本質(zhì)是代理在處理 Codex 的/responses端點時轉(zhuǎn)發(fā)規(guī)則沒有覆蓋到這個路徑。Codex 的 API 路徑和 Claude 不太一樣Claude 用的是/v1/messagesCodex 用的是/responses。如果你的代理規(guī)則只寫了/v1/*那 Codex 的請求就會漏掉。解決方法是在代理配置里顯式加上/responses路徑的轉(zhuǎn)發(fā)規(guī)則。4.2 模型接入的兼容性問題接入第三方模型時最大的問題是 API 格式兼容性。Claude Code 和 Codex 各自期望的請求格式不同而第三方模型供應(yīng)商的 API 格式又各有差異。openrig 的代理層需要做格式轉(zhuǎn)換。以 DeepSeek 為例它的 API 格式和 OpenAI 兼容但和 Claude 的格式有差異。如果你直接用 Claude Code 去調(diào) DeepSeek 的接口會報格式錯誤。解決方法是在代理層做轉(zhuǎn)換// 簡化的格式轉(zhuǎn)換邏輯 function convertClaudeToOpenAI(claudeRequest) { return { model: claudeRequest.model, messages: claudeRequest.messages.map(msg ({ role: msg.role assistant ? assistant : user, content: typeof msg.content string ? msg.content : msg.content.map(c c.text).join() })), max_tokens: claudeRequest.max_tokens, temperature: claudeRequest.temperature }; }這個轉(zhuǎn)換邏輯看起來簡單但實際要處理的邊界情況很多。比如 Claude 的system字段在 OpenAI 格式里要放到 messages 數(shù)組的第一條stop_sequences要改成stop工具調(diào)用的格式也不一樣。我建議直接用現(xiàn)成的轉(zhuǎn)換庫比如anthropic-ai/sdk配合openai包做適配不要自己從頭寫。另一個坑是流式響應(yīng)的處理。Claude 和 OpenAI 的流式格式不同Claude 用event: content_block_deltaOpenAI 用data: {choices:[{delta:...}]}。代理層需要把兩種格式互相轉(zhuǎn)換否則 Claude Code 會解析不了響應(yīng)。4.3 性能調(diào)優(yōu)與穩(wěn)定性建議跑了一段時間之后我總結(jié)了幾條調(diào)優(yōu)經(jīng)驗第一給代理層加緩存。對于重復(fù)的請求比如相同的代碼補全請求可以在代理層做短期緩存。我用了一個簡單的內(nèi)存緩存TTL 設(shè) 60 秒命中率大概有 15% 左右響應(yīng)速度明顯提升。第二設(shè)置合理的超時時間。Claude Code 默認的超時可能比較長遇到網(wǎng)絡(luò)問題時體驗很差。在 openrig 配置里把timeout設(shè)成 120 秒比較合適太短了長任務(wù)會中斷太長了卡住等得難受。第三日志分級。開發(fā)階段把log_level設(shè)成debug能看到完整的請求和響應(yīng)。生產(chǎn)使用時改成warn避免日志文件膨脹。我見過有人忘了改日志級別跑了一周日志文件幾十個 G。第四定期檢查 API Key 余額。第三方模型供應(yīng)商的余額不足時報錯信息往往不直觀可能表現(xiàn)為請求超時或者返回空響應(yīng)。在 openrig 里加一個余額檢查的定時任務(wù)余額低于閾值時發(fā)通知。// 簡單的余額檢查 async function checkBalance(provider) { const resp await fetch(${provider.base_url}/user/balance, { headers: { Authorization: Bearer ${process.env[provider.api_key_env]} } }); const data await resp.json(); if (data.balance 10) { console.warn(${provider.name} 余額不足: ${data.balance}); } }4.4 跨平臺使用的注意事項Windows、macOS、Linux 三個平臺我都跑過 openrig各有各的坑。Windows 上最大的問題是路徑分隔符和 shell 差異。Node.js 的spawn在 Windows 上默認不通過 shell 執(zhí)行導致一些命令找不到。解決方法是在spawn參數(shù)里加shell: true但這樣又可能引入命令注入風險。我的做法是只在 Windows 平臺加shell: true并且對傳入的參數(shù)做轉(zhuǎn)義。macOS 上相對省心但要注意 Apple Silicon 和 Intel 的架構(gòu)差異。有些 npm 包在 M 系列芯片上需要重新編譯如果遇到invalid ELF header之類的報錯刪掉node_modules重新npm install通常能解決。Ubuntu 上的坑主要在權(quán)限和 systemd 集成。如果你想把 openrig 做成開機自啟的服務(wù)需要寫一個 systemd unit 文件[Unit] DescriptionOpenRig Proxy Service Afternetwork.target [Service] Typesimple Useryouruser WorkingDirectory/home/youruser/openrig ExecStart/usr/bin/node /home/youruser/openrig/bin/proxy.js Restarton-failure EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target放到/etc/systemd/system/openrig.service然后systemctl enable --now openrig就能開機自啟了。5. 進階玩法把 openrig 用出花來5.1 多模型路由與自動降級openrig 的配置結(jié)構(gòu)天然支持多模型路由。你可以在 profile 里定義一個模型優(yōu)先級列表當主模型不可用時自動切換到備用模型profiles: resilient: provider: anthropic model: sonnet fallback: - provider: deepseek model: ds-chat - provider: glm model: glm4啟動腳本里實現(xiàn)降級邏輯先試主模型請求失敗超時或返回錯誤碼就切到下一個。這個邏輯用 Node.js 的try/catch加循環(huán)就能實現(xiàn)但要注意區(qū)分“可重試錯誤”和“不可重試錯誤”。比如 401 認證失敗重試多少次都沒用直接報錯而 429 限流或者 503 服務(wù)不可用就值得重試。我實測下來這套降級機制在主力模型偶爾抽風的時候特別管用。有一次 Claude 的 API 返回 503openrig 自動切到 DeepSeek整個開發(fā)流程沒有中斷我甚至沒注意到切換發(fā)生了。5.2 與 VS Code 的集成Claude Code 有 VS Code 擴展openrig 可以和它配合使用。在 VS Code 的settings.json里配置{ claude-code.environment: { OPENRIG_PROFILE: dev, OPENRIG_CONFIG: /Users/yourname/openrig/openrig.yaml } }這樣在 VS Code 里啟動 Claude Code 時它會讀取 openrig 的配置。不過要注意VS Code 擴展啟動的進程可能不會繼承你 shell 里的環(huán)境變量所以 API Key 需要在 VS Code 的設(shè)置里單獨配置或者通過terminal.integrated.env注入。另一個集成點是用 VS Code 的任務(wù)系統(tǒng)跑 openrig 命令。在.vscode/tasks.json里定義一個任務(wù){(diào) version: 2.0.0, tasks: [ { label: openrig: dev, type: shell, command: openrig dev, problemMatcher: [] } ] }按CtrlShiftP然后選Tasks: Run Task就能快速啟動。5.3 配置模板化與團隊共享如果你在團隊里推廣 openrig可以做一個配置模板倉庫。把通用的 provider 定義、代理設(shè)置、profile 結(jié)構(gòu)放在模板里團隊成員 clone 之后只需要填自己的 API Key 和個性化配置。模板倉庫的結(jié)構(gòu)大概是這樣openrig-template/ ├── openrig.yaml # 主配置模板 ├── profiles/ │ ├── dev.yaml # 開發(fā)環(huán)境 │ ├── staging.yaml # 預(yù)發(fā)環(huán)境 │ └── prod.yaml # 生產(chǎn)環(huán)境 ├── bin/ │ └── openrig.js # 啟動腳本 ├── package.json └── README.md # 使用說明主配置里用 YAML 的!include指令需要自定義 YAML 類型或者啟動腳本里做文件合并把 profiles 目錄下的配置合并進來。這樣每個人只需要維護自己的 profile 文件公共部分由模板統(tǒng)一管理。團隊共享時還要注意 API Key 的管理。絕對不要把 Key 寫進配置文件提交到倉庫?？梢杂?env文件加.gitignore的方式或者用團隊統(tǒng)一的密鑰管理服務(wù)。我見過有人不小心把 Key 提交到公開倉庫幾分鐘內(nèi)就被掃到并盜用了損失不小。5.4 監(jiān)控與日志分析跑了一段時間后你可能會想知道哪個模型用得最多平均響應(yīng)時間是多少哪些請求經(jīng)常失敗這些數(shù)據(jù)對優(yōu)化配置很有幫助。在 openrig 的代理層加一個簡單的日志記錄把每次請求的元數(shù)據(jù)寫到 JSON Lines 文件function logRequest(entry) { const line JSON.stringify({ timestamp: new Date().toISOString(), provider: entry.provider, model: entry.model, duration: entry.duration, status: entry.status, tokens: entry.tokens }); fs.appendFileSync(openrig.log, line \n); }然后用jq或者寫個小腳本做分析# 統(tǒng)計各模型使用次數(shù) cat openrig.log | jq -r .model | sort | uniq -c | sort -rn # 計算平均響應(yīng)時間 cat openrig.log | jq -s map(.duration) | add / length這些數(shù)據(jù)幫我發(fā)現(xiàn)了一個問題我原以為 DeepSeek Coder 在代碼任務(wù)上更快但實際數(shù)據(jù)顯示 Claude Sonnet 的平均響應(yīng)時間反而更短。后來調(diào)整了默認模型開發(fā)效率提升了不少。6. 我踩過的那些坑說幾個印象深刻的翻車經(jīng)歷希望能幫你省點時間。第一個坑是 YAML 的縮進。YAML 對縮進極其敏感用 Tab 還是空格、縮進幾個空格都有講究。我有次從網(wǎng)頁上復(fù)制了一段配置粘貼進去之后一直報解析錯誤查了半天才發(fā)現(xiàn)是混合用了 Tab 和空格。后來在編輯器里設(shè)置了tab_size: 2并且開啟render_whitespace這類問題就少多了。第二個坑是環(huán)境變量的繼承。openrig 啟動子進程時如果直接傳env對象子進程的環(huán)境變量就是完全替換而不是追加。我一開始沒注意導致 Claude Code 找不到PATH連基本命令都執(zhí)行不了。正確的做法是{ ...process.env, ...customEnv }先繼承再覆蓋。第三個坑是代理的NO_PROXY設(shè)置。我本地跑了一個模型服務(wù)在localhost:8080但請求一直走代理繞了一圈。后來發(fā)現(xiàn)NO_PROXY里寫的是localhost但實際請求用的是127.0.0.1兩者在代理規(guī)則里不等價。把兩個都加上就好了。第四個坑是 Node.js 版本升級導致的兼容性問題。有次我把 Node.js 從 20 升到 22結(jié)果js-yaml包報了個奇怪的錯誤。查了才知道是包版本太老不支持新的 Node.js API。升級js-yaml到最新版就解決了。所以升級 Node.js 大版本時記得把依賴包也更新一遍。第五個坑是 API Key 的權(quán)限范圍。有些平臺的 API Key 可以設(shè)置權(quán)限范圍比如只讀、只寫、或者限定模型。我申請了一個 Key 用來測試結(jié)果一直報 403后來發(fā)現(xiàn)是申請時沒勾選對應(yīng)的模型權(quán)限。這個坑不常見但遇到了很難排查因為報錯信息不會告訴你具體缺哪個權(quán)限。這些經(jīng)驗歸結(jié)起來就是一句話配置管理這件事細節(jié)決定成敗。openrig 的思路是把所有細節(jié)顯式化、結(jié)構(gòu)化讓你能一眼看到全貌而不是散落在各個 shell 配置文件和環(huán)境變量里。剛開始搭建的時候多花點時間后面用起來就省心了。