1. 从 openrig 说起一个把 Claude Code 和 Codex 拉回本地可控的编排层第一次看到openrig这个名字我下意识把它拆成了 “open” 和 “rig” 两半。rig 在工程语境里从来不是“随便搭一下”的意思它指的是把一堆零散部件固定成一套能稳定运转的装置——钻井平台叫 rig舞台灯光架叫 rig测试台架也叫 rig。所以 openrig 给我的第一直觉就是它不是一个模型也不是一个 CLI 工具而是一层用来“架住” Claude Code、Codex 这类编码代理的编排骨架。这个判断和热搜词高度吻合。openrig,Claude Code,Codex,YAML,Node.js这五个词放在一起基本勾勒出了它的技术画像用 Node.js 做运行时用 YAML 做声明式配置把 Claude Code 和 Codex 这两个当下最主流的终端编码代理统一到一套可切换、可复用、可版本管理的配置体系里。它解决的不是“模型够不够聪明”的问题而是“我手上有三四个代理、五六套 API、七八个项目怎么让它们不打架”的问题。我自己的日常就是这种状态。白天在 VS Code 里用 Claude Code 改业务代码晚上用 Codex CLI 跑一些批量重构中间还要切到本地 LM Studio 上验证小模型的表现。以前每换一个环境就要重新配一遍环境变量、改一遍配置文件、确认一遍端点地址切来切去非常容易出错。openrig 这类工具的价值就在于它把“代理怎么连、连哪个端点、用哪个模型、走哪套参数”这件事从散落在 shell 配置里的碎片收敛成了一份可以提交到 Git 的 YAML。适合读这篇的人有三类。第一类是刚接触 Claude Code 或 Codex、还在被cc switch local proxy failed while handling codex endpoint /responses这类报错折磨的新手第二类是已经在用多个代理、但配置管理一团乱麻的中级用户第三类是想把团队里所有人的代理配置统一起来、避免“我这能跑你那不能跑”的工程负责人。下面我会按 openrig 的思路把配置设计、环境搭建、实操流程和踩坑排查完整拆一遍尽量做到你照着抄就能跑起来。2. openrig 的整体设计思路与方案选型2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置载体这个决定看似平常其实很关键。JSON 不支持注释而代理配置里最需要的就是注释——你得写清楚“这个端点是谁的”“这个模型名对应哪个供应商”“这行参数为什么这么设”。TOML 虽然支持注释但嵌套结构一深就变得很啰嗦尤其是当你要描述“多个代理 × 多个供应商 × 多个模型”这种三维关系时TOML 的[a.b.c.d]表头会迅速失控。YAML 的优势在于它天然适合表达层级和列表。一个典型的 openrig 配置大概长这样version: 1 defaults: timeout: 120 retries: 2 providers: - name: anthropic-main type: anthropic base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY - name: local-lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key_env: LMSTUDIO_KEY agents: - name: claude-code provider: anthropic-main model: claude-sonnet-4-5 env: CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 - name: codex provider: local-lmstudio model: qwen2.5-coder-14b env: CODEX_DISABLE_TELEMETRY: 1这种结构一眼就能看懂谁连谁。更重要的是YAML 可以被程序化生成也可以被人工手改两边都不别扭。我在实际项目里经常用脚本从环境变量里读出密钥再渲染进 YAML 模板最后交给 openrig 加载整个流程非常顺。注意YAML 对缩进极其敏感Tab 和空格混用是最常见的“配置看起来没问题但就是加载失败”的元凶。建议在编辑器里强制把 Tab 转成 2 个空格并在 CI 里加一步 YAML lint。2.2 为什么用 Node.js 做运行时热搜词里node.js、node.js安装、node.js下载、node.js lts下载出现频率极高说明很多人卡在第一步。openrig 选 Node.js 不是偶然Claude Code 和 Codex 的 CLI 本身都深度依赖 Node 生态很多插件、MCP server、代理转发脚本也都是 npm 包。用 Node.js 做 openrig 的运行时意味着它可以直接复用这些生态而不需要用户再装一套 Python 或 Go 环境。另一个现实原因是跨平台。Node.js 在 Windows、macOS、Linux 上的行为一致性相当好一份 openrig 配置在三端都能跑。相比之下如果用 shell 脚本做编排Windows 用户基本就被劝退了。我见过太多团队因为“配置脚本只支持 bash”而导致 Windows 同事无法参与最后只能维护两套流程维护成本翻倍。Node.js 的版本选择也有讲究。热搜里出现了error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错说明有人试图装一个还不存在的版本。我的建议是直接用 LTS 版本目前稳定在 20.x 或 22.x。LTS 的意义不只是“稳定”更关键的是原生模块native addon的预编译包覆盖最全。如果你用奇数版本或者刚发布的偶数版本很可能遇到某个依赖需要现场编译而现场编译又依赖 Python 和 C 工具链一步错步步错。2.3 把 Claude Code 和 Codex 统一编排的核心动机Claude Code 和 Codex 虽然都是终端编码代理但它们的配置哲学完全不同。Claude Code 偏向“环境变量 项目内配置文件”Codex 偏向“全局配置 命令行参数”。如果你同时用这两个就会陷入一种割裂改 Claude Code 的配置要去动.claude目录改 Codex 的配置要去动~/.codex两边格式还不一样。openrig 的核心动机就是把这层差异抹平。它不试图替换任何一个代理而是站在它们之上做一层“翻译”你只写一份 openrig YAML它负责在启动时把配置渲染成各个代理认识的形式。这样带来的直接好处是切换代理只需要改一行agent: codex而不是重新配一遍环境。这个设计还有一个隐性收益可审计。当所有配置都在一份 YAML 里你就能用 Git 追踪“谁在什么时候把模型从 A 换成了 B”。在团队协作里这种可追溯性比省那几分钟配置时间重要得多。我经历过一次线上事故最后定位到是某位同事本地把端点改成了测试环境但没同步如果当时有 openrig 这样的统一配置层这个问题在 code review 阶段就会被发现。3. 环境准备Node.js 与基础依赖的正确安装姿势3.1 Node.js 版本选择与安装路径先把最容易翻车的一步讲透。热搜里node.js安装、node.js下载、node.js官网下载、安装node.js、ubuntu安装node.js 20这些词反复出现说明安装环节是新手最大的门槛。我的建议是不要从官网下载安装包手动装而是用版本管理器。在 macOS 和 Linux 上nvm是最省心的选择curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 nvm alias default 20在 Windows 上推荐用nvm-windows或者直接装 LTS 的 MSI 安装包。如果你用 WSL那就按 Linux 的方式走。为什么强调版本管理器因为 openrig 这类工具经常需要同时兼容多个 Node 版本。你可能主项目用 20但某个老项目还锁在 18。用 nvm 切换只需要一条命令而手动装的话你得卸载重装非常痛苦。提示安装完成后务必执行node -v和npm -v确认版本。如果node -v报“command not found”大概率是 PATH 没配好检查~/.bashrc或~/.zshrc里有没有 nvm 的初始化脚本。3.2 全局包管理与权限问题Node.js 装好后下一步是装 openrig 本身。这里有个经典坑直接用npm install -g在 Linux 上可能因为权限问题失败报EACCES。很多人第一反应是加sudo但sudo npm install -g会把包装到 root 目录下后续普通用户运行时又找不到反而更乱。正确的做法是配置 npm 的全局目录到用户空间mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc这样之后所有npm install -g都装到你的家目录不需要 sudo也不会污染系统目录。这个配置我建议所有 Node.js 用户都做一遍不只是为了 openrig。3.3 代理 CLI 的前置安装openrig 是编排层它本身不包含 Claude Code 和 Codex 的二进制。所以你需要先把这两个装上。Claude Code 通常通过 npm 安装npm install -g anthropic-ai/claude-codeCodex 的安装方式取决于你用的发行版常见的是通过 npm 或官方安装脚本。装完后分别执行claude --version和codex --version确认可用。这里有个容易被忽略的点Claude Code 和 Codex 都可能依赖特定的 Node 版本。如果你用 nvm 切换了版本全局包不会自动跟着走需要在新版本下重新npm install -g。我踩过这个坑切到 Node 18 后 Claude Code 直接报模块找不到排查了半小时才反应过来是全局包不共享。组件推荐版本安装方式验证命令Node.js20.x LTSnvm / MSInode -vnpm随 Node 附带无需单独装npm -vClaude Code最新稳定版npm install -gclaude --versionCodex最新稳定版npm 或官方脚本codex --versionopenrig最新稳定版npm install -gopenrig --version4. openrig 配置文件的完整实操4.1 初始化与目录结构openrig 的配置通常放在项目根目录或者用户主目录下。我的习惯是在项目根目录建一个.openrig/文件夹里面放config.yaml和若干环境覆盖文件project/ ├── .openrig/ │ ├── config.yaml # 主配置 │ ├── config.local.yaml # 本地覆盖加入 .gitignore │ └── prompts/ # 可复用的提示词模板 ├── src/ └── package.json这种分层的好处是主配置可以提交到 Git 供团队共享本地覆盖文件放个人密钥和临时调整。openrig 加载时会先读主配置再用本地文件覆盖符合“约定优于配置”的思路。初始化命令一般是openrig init它会生成一份带注释的模板配置。我建议不要直接删掉注释那些注释里往往藏着关键参数的说明留着当文档用。4.2 供应商与端点的配置细节配置里最容易出错的是base_url和api_key_env这两项。base_url必须指向真正的 API 根路径不能多也不能少斜杠。比如 OpenAI 兼容端点通常是http://host:port/v1如果你写成http://host:port/v1/某些客户端会拼出//chat/completions这种双斜杠路径导致 404。api_key_env的设计很聪明它不直接写密钥而是写环境变量的名字。这样配置文件可以安全地提交到仓库密钥通过 shell 或.env文件注入。我通常会在.bashrc里这样写export ANTHROPIC_API_KEYsk-ant-xxxx export LMSTUDIO_KEYnot-needed-but-must-exist注意本地 LM Studio 这类服务通常不校验密钥但很多客户端要求这个字段非空所以随便填一个占位符即可。注意千万不要把真实密钥写进 YAML 再提交。即使后来删掉Git 历史里依然能翻出来。一旦泄露第一件事是去供应商后台吊销密钥而不是改文件。4.3 代理切换与参数覆盖openrig 最实用的功能是代理切换。假设你配置了三个 agentclaude-code、codex、codex-local。切换只需要openrig use codex-local openrig run 重构这个函数它会在后台把对应的环境变量和配置注入到 Codex 进程里。你不需要手动export一堆变量也不需要改~/.codex/config。参数覆盖是另一个高频需求。比如你平时用默认模型但某个任务想临时换一个更强的模型openrig run --model claude-opus-4-5 分析这段代码的性能瓶颈这种命令行覆盖的优先级高于 YAML 里的配置符合“就近原则”。我在做性能敏感任务时经常这么干避免为了一个临时需求去改配置文件。4.4 与 VS Code 的集成热搜里vscode配置claude code、vscode接入claude code、claude code for vs code出现多次说明很多人希望在编辑器里直接用。openrig 本身是 CLI 工具但它可以和 VS Code 的任务系统结合。在.vscode/tasks.json里加一个任务{ version: 2.0.0, tasks: [ { label: openrig: claude-code, type: shell, command: openrig run --agent claude-code \${input:prompt}\, problemMatcher: [] } ], inputs: [ { id: prompt, type: promptString, description: 输入你的指令 } ] }这样按CtrlShiftP运行任务就能直接调用。虽然不如原生插件顺滑但胜在配置透明、可版本管理。我团队里有人更喜欢这种“看得见每一步”的方式尤其是需要审计调用记录的场景。5. 常见报错与排查技巧实录5.1 端点与代理类报错热搜里cc switch local proxy failed while handling codex endpoint /responses这个报错非常典型。它的字面意思是在切换本地代理时处理 Codex 的/responses端点失败了。根因通常有三个一是本地代理服务没启动二是base_url指向的路径不对三是 Codex 期望的端点和代理实际提供的端点不匹配。排查顺序我建议这样走先用curl直接打端点确认服务活着curl -s http://127.0.0.1:1234/v1/models如果这条命令返回模型列表说明服务正常问题在 openrig 或 Codex 的配置。如果返回连接拒绝那就是服务没起来。如果返回 404说明路径不对检查base_url是否包含了/v1。还有一个隐蔽的坑某些本地服务只监听localhost而不监听127.0.0.1或者反过来。在 IPv6 优先的系统上localhost可能解析到::1而服务只绑了 IPv4。这种情况直接把base_url写成127.0.0.1就能绕开。5.2 模型不支持类报错{detail:the gpt-5.6-sol model is not supported when using codex with a...}这类报错说明你请求的模型名不在服务端的支持列表里。原因可能是模型名拼写错误也可能是你用的代理服务只支持特定模型。解决方法是先列出可用模型curl -s http://127.0.0.1:1234/v1/models | jq .data[].id然后把 YAML 里的model字段改成列表里真实存在的名字。我见过有人把qwen2.5-coder写成qwen-2.5-coder就差一个连字符排查了半天。5.3 组织与订阅类报错your organization has disabled claude subscription access for claude code和codex无法加载组织设置这两类报错属于账号层面。前者通常是企业管理员在后台关闭了某个功能的访问权限个人用户无法自行解决需要联系管理员。后者可能是网络请求组织配置时超时或返回异常先检查网络连通性再确认账号是否有权限访问该组织。这类问题我的经验是不要急着改配置先确认“是不是账号本身的问题”。用一个最小化的curl请求直接打官方 API如果官方 API 也报同样的错那就和 openrig 无关。5.4 常见问题速查表报错关键词可能原因排查动作proxy failed while handling endpoint本地服务未启动或路径错误curl直连端点验证model is not supported模型名错误或服务不支持列出/v1/models核对organization has disabled账号权限被限制联系管理员确认EACCES安装失败npm 全局目录权限问题配置~/.npm-globalcommand not foundPATH 未包含安装目录检查 shell 配置文件YAML 加载失败缩进或 Tab 混用用 lint 工具校验提示遇到报错先看最后一行再看倒数第二行。很多人的习惯是从上往下读但真正的原因往往在堆栈底部。我排查时习惯先tail -n 20看结尾能省不少时间。6. 把 openrig 用顺手的几个进阶技巧6.1 用环境覆盖文件管理多套配置真实工作里你往往需要在“公司内网端点”和“家里本地端点”之间切换。与其每次手改 YAML不如准备多个覆盖文件.openrig/ ├── config.yaml ├── config.office.yaml ├── config.home.yaml └── config.local.yaml然后通过环境变量指定加载哪个OPENRIG_PROFILEoffice openrig run 跑一下测试这种 profile 机制在团队里特别有用。新同事入职只需要拿到config.office.yaml不用理解全部配置细节就能跑起来。6.2 把提示词模板也纳入版本管理openrig 的prompts/目录可以放可复用的提示词。比如refactor.md、review.md、test-gen.md。调用时直接引用openrig run --prompt refactor 把这段代码拆成三个函数这样做的好处是提示词可以像代码一样 review 和迭代。我团队里有个review.md模板经过十几轮打磨现在用它做代码审查的准确率比随手写的提示词高出一大截。6.3 日志与审计openrig 通常会记录每次调用的元信息时间、agent、模型、token 消耗。这些日志不要随手删它们在排查“为什么这个月费用涨了”时非常有用。我习惯把日志按天归档月底做一次汇总看看哪个 agent 用得最多、哪个模型最费钱。如果团队有成本控制需求可以在 YAML 里给每个 agent 设置max_tokens上限避免某次失控的调用烧掉大量额度。这个上限不是越小越好太小会导致输出被截断反而要重跑。我的经验值是给代码生成类任务留 8192给分析类任务留 4096。6.4 与本地模型的配合热搜里claude code 调用lmstudio的本地模型说明很多人想用本地模型省钱或保隐私。openrig 对这类场景支持得很好只要把 provider 的type设成openai-compatiblebase_url指向 LM Studio 的地址即可。但要注意本地小模型的指令遵循能力通常弱于云端大模型。同样的提示词云端模型能一次做对本地模型可能要重试两三次。所以我在本地模型上跑任务时会把提示词写得更结构化把步骤拆得更细减少模型自由发挥的空间。实测下来这种“喂到嘴边”的写法能显著提升本地模型的成功率。7. 我踩过的坑和最后几句实在话openrig 这类工具最大的价值不是让你少敲几条命令而是把“配置”这件事从个人习惯变成团队资产。我见过太多团队因为每个人的代理配置不一样导致同一个任务在不同机器上结果不同最后浪费大量时间在“你那边怎么跑的”这种对话上。统一到一份 YAML 之后这类扯皮基本消失。我自己踩过最深的坑是 YAML 缩进。有一次用脚本生成配置脚本里用了 Tab手改的部分用了空格结果 openrig 加载时报了一个非常模糊的解析错误我对着文件看了二十分钟才发现问题。从那以后我在所有项目里都加了 pre-commit hook提交前自动跑 YAML lint再也没犯过。另一个坑是密钥管理。早期我图省事把密钥直接写在 YAML 里后来有一次不小心把配置文件推到了公开仓库虽然几分钟内就删了但那种后背发凉的感觉至今记得。现在我的原则是配置文件里永远只出现环境变量名真实密钥只存在于 shell 环境和 CI 的 secret 里。如果你刚开始用 openrig我的建议是先跑通一个最小配置一个 provider、一个 agent、一个模型。确认能正常调用之后再逐步加第二个 provider、第二个 agent。不要一上来就配五六个端点那样出问题时你根本不知道是哪一层坏了。配置这件事和写代码一样小步快跑比一次性写完更靠谱。