1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里常指设备支架、测试台架。翻了翻社区讨论和几个相关仓库之后才反应过来它更像是围绕 Claude Code、Codex 这类命令行 AI 编程工具做的一套本地配置与代理编排方案。说白了openrig 想解决的核心问题是当你同时装了 Claude Code、Codex CLI又想在本地接 LM Studio、DeepSeek、Qwen、GLM 这些模型时配置文件散落各处、端点互相打架、YAML 写错一个缩进就报错整个环境乱成一锅粥。我自己的机器上就长期跑着 Node.js 环境装过 Claude Code也折腾过 Codex 的接入。最头疼的不是工具本身而是每次换模型、换端点都要去翻不同的配置文件改完还得重启终端验证。openrig 这类项目的价值就在于把这些零散的配置收拢到一套 YAML 驱动的结构里用一个统一的入口去管理多个 AI 编程工具的运行时参数。它适合谁如果你只是偶尔用用网页版对话那完全不需要。但如果你满足下面任意一条openrig 这套思路就值得研究在终端里高频使用 Claude Code 或 Codex需要在本机跑 LM Studio 加载本地模型团队里多人共用一套模型接入配置经常遇到cc switch local proxy failed while handling codex endpoint /responses这类端点报错。这些场景我都踩过后面会逐个拆开讲。需要先说明的是openrig 目前并不是一个官方大一统工具社区里围绕它的讨论更多是配置实践和经验汇总。所以这篇文章我不会假装它有一个完美文档而是按一个真实使用者的视角把 YAML 配置、Node.js 环境、Claude Code 与 Codex 接入这几块讲透让你能照着搭起来。2. 环境底座Node.js 与 YAML 的正确打开方式2.1 Node.js 安装为什么总是第一步就翻车Claude Code 和 Codex CLI 绝大多数情况下都是基于 Node.js 生态分发的所以 Node.js 是绕不开的地基。但恰恰是这一步新手最容易卡住。我见过太多人搜到error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错然后一脸懵。这个报错的本质是你用的版本管理器或者安装脚本去拉一个还不存在的版本号。Node.js 的版本发布是有节奏的奇数版本是过渡版偶数版本才是 LTS长期支持版。生产环境或者日常开发我强烈建议直接上 LTS别追最新的奇数版。具体操作上Windows 用户直接去 Node.js 官网下载 LTS 的安装包一路下一步就行。但我要提醒一个坑安装时那个 Add to PATH 的勾一定要留着否则装完在终端敲node -v会提示找不到命令。Mac 和 Ubuntu 用户我更推荐用版本管理器比如 nvm这样以后切换版本不用重装。# Ubuntu 下用 nvm 安装 Node.js LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v npm -v装完之后验证两个命令node -v和npm -v。两个都能输出版本号才算真正装好。我遇到过只装了 node 没装 npm 的情况那是因为用了某些精简版安装方式这时候得单独补 npm。提示如果你在国内网络环境下 npm 安装依赖特别慢可以配置镜像源但不要用来源不明的第三方脚本优先用官方文档给出的方式。2.2 YAML 文件到底该怎么创建才不出错YAML 是 openrig 这类配置方案的核心载体。热词里有人问 yolov10 yaml 文件怎么创建、rstudio 的 yaml 在哪里说明很多人对 YAML 的认知还停留在听说过但没写过。其实 YAML 就是一种用缩进表达层级的数据格式比 JSON 好读但对缩进极其敏感。创建 YAML 文件本身没有任何神秘操作新建一个文本文件把扩展名改成.yaml或.yml就行。真正难的是内容写对。我总结了几条铁律都是血泪教训缩进只能用空格绝对不能用 Tab。这是 YAML 报错的第一大来源编辑器里看着对齐了实际一个是 Tab 一个是空格解析器直接罢工。冒号后面必须跟一个空格key:value是错的key: value才是对的。字符串如果包含特殊字符用引号包起来单引号双引号都行但要注意转义规则不同。层级关系靠缩进同一层级缩进量必须一致通常用两个空格。# 一个典型的 openrig 风格配置示例 runtime: node: version: 20.11.0 packageManager: npm proxy: enabled: true host: 127.0.0.1 port: 8787 providers: - name: local-lmstudio type: openai-compatible baseUrl: http://127.0.0.1:1234/v1 model: local-model - name: deepseek type: openai-compatible baseUrl: https://api.deepseek.com/v1 model: deepseek-chat tools: claude-code: provider: local-lmstudio codex: provider: deepseek上面这段配置我故意写得贴近真实使用场景。runtime管运行环境providers列出所有可用的模型端点tools把具体工具绑定到某个 provider 上。这样改模型只需要动tools里的引用不用去每个工具的独立配置里翻。注意YAML 里true、false、数字、null会被自动识别成对应类型如果你就是想要字符串 true记得加引号。这个坑我在配置端口号时踩过写了个没加引号的数字结果被当成整数处理拼接 URL 时类型不对直接报错。2.3 用编辑器校验 YAML别靠肉眼我强烈建议在 VS Code 里装一个 YAML 插件它能实时标红缩进错误和语法问题。很多人写完 YAML 直接运行报错了再回来一行行找效率极低。插件会在你敲键盘的时候就告诉你哪一行有问题省下大量排查时间。另外YAML 文件的位置也有讲究。openrig 这类方案通常约定一个项目根目录下的配置文件比如openrig.yaml或者放在.config目录里。你要先确认工具默认去哪里读配置再决定文件放哪。放错位置配置写得再对也不生效这个我后面在排查章节会详细讲。3. Claude Code 与 Codex 的接入实战3.1 Claude Code 安装与配置的完整链路Claude Code 是 Anthropic 推出的命令行编程助手能在终端里直接读写文件、执行命令。热词里 claude code 安装、claude code 下载、claude code windows、ubuntu 配置 claude code 全都在问同一件事怎么把它跑起来。安装本身不复杂通过 npm 全局安装即可npm install -g anthropic-ai/claude-code装完之后在项目目录里敲claude就能启动。但这里有个高频报错your organization has disabled claude subscription access for claude code。这个提示的意思是你当前登录的账号所属组织关闭了 Claude Code 的订阅访问权限。遇到这个先确认你用的是个人账号还是组织账号组织账号需要管理员在后台开启对应权限。这不是配置问题是账号权限问题改配置文件没用。另一个常见需求是让 Claude Code 调用本地模型比如 LM Studio。热词里 claude code 调用 lmstudio 的本地模型 就是典型场景。思路是把 Claude Code 的请求指向一个本地代理代理再把请求转发给 LM Studio 的 OpenAI 兼容端点。openrig 的providers配置就是干这个的。# 设置环境变量指向本地代理端点 export ANTHROPIC_BASE_URLhttp://127.0.0.1:8787 export ANTHROPIC_API_KEYlocal-key claude提示本地模型的能力和云端大模型差距明显用它跑 Claude Code 更多是出于隐私或离线需求。别指望本地小模型能完美处理复杂的多文件重构任务心里要有预期。VS Code 用户还可以装 Claude Code 的官方扩展在编辑器里直接调用。热词里 vscode 配置 claude code、claude code for vs code 说的就是这个。装完扩展后在设置里填好端点信息就能在侧边栏对话了。3.2 Codex 安装与端点报错的排查Codex 这边的情况稍微复杂一点。热词里 codex 安装、codex 安装教程、codex 安装 windows 桌面版、codex cli 说明大家对这个工具的安装路径还不太清楚。Codex 有 CLI 版本也有和编辑器集成的形态安装方式取决于你要用哪种。CLI 版本同样走 npmnpm install -g openai/codex装完敲codex启动。但真正让人抓狂的是端点报错。热词里那条cc switch local proxy failed while handling codex endpoint /responses我印象特别深因为我自己就遇到过。这个报错拆开看cc switch是切换配置的动作local proxy failed是本地代理转发失败handling codex endpoint /responses说明问题出在处理 Codex 的/responses这个端点上。排查思路是这样的先确认本地代理服务是否真的在运行。curl http://127.0.0.1:8787/health之类的健康检查端点能不能通。再确认代理配置里/responses这个路径有没有正确映射到上游。Codex 用的端点和普通 chat 端点不一样如果代理只配了/v1/chat/completions而没配/responses就会转发失败。检查上游模型是否支持 Codex 要求的接口格式。热词里the gpt-5.6-sol model is not supported when using codex with a这类报错就是模型名和 Codex 期望的不匹配。# 代理路由配置示例关键是覆盖 codex 需要的端点 routes: - path: /responses target: http://127.0.0.1:1234/v1/responses - path: /v1/chat/completions target: http://127.0.0.1:1234/v1/chat/completions我踩过的坑是代理配置里路径写成了/response少了个 s结果 Codex 请求/responses时匹配不上直接 404。这种拼写错误肉眼极难发现一定要用日志把实际请求路径打出来对比。3.3 用 cc switch 在多个模型间切换热词里 使用 cc switch 接入 deepseek v4, qwen, glm 等模型 点出了一个真实痛点不同任务适合不同模型但每次切换都要改配置、重启工具太麻烦。cc switch 这类工具的思路是维护多套配置一条命令切换。在 openrig 的 YAML 结构里这对应的是providers列表和tools的绑定关系。你可以把所有模型都列在providers里然后通过切换tools下的 provider 引用来换模型。# 假设 openrig 提供了切换命令 openrig switch codex --provider deepseek openrig switch claude-code --provider local-lmstudio切换之后记得验证新起的会话是不是真的走了新端点。我一般会在代理日志里看请求打到了哪个上游确认切换生效。有时候配置改了但工具进程没重启还在用旧配置这种改了没生效的问题十有八九是进程没重启。注意不同模型对接口参数的支持程度不一样。DeepSeek、Qwen、GLM 虽然都提供 OpenAI 兼容接口但在max_tokens、temperature的取值范围和默认值上有差异。切换模型后如果出现参数报错先去看对应模型的接口文档别硬套另一家的参数。4. 配置管理与常见故障速查4.1 把散落的配置收拢成一套在没有 openrig 这类方案之前我的配置是这样的Claude Code 的环境变量写在.bashrc里Codex 的配置在它自己的目录下LM Studio 的端点在另一个地方代理又是单独一份。改一个模型要动三四个文件改漏一个就出诡异问题。openrig 的核心价值就是把它们收拢。我的做法是项目根目录放一份openrig.yaml作为唯一事实来源然后用一个启动脚本读取这份 YAML导出对应的环境变量再拉起各个工具。#!/usr/bin/env bash # 从 openrig.yaml 读取配置并导出环境变量 export ANTHROPIC_BASE_URL$(yq .runtime.proxy.host : (.runtime.proxy.port | tostring) openrig.yaml) export OPENAI_BASE_URL$ANTHROPIC_BASE_URL echo 端点已设置为: $ANTHROPIC_BASE_URL这里用到了yq这个命令行 YAML 处理工具它能像jq处理 JSON 一样处理 YAML。装好之后解析配置就是一行命令的事比手写 sed、awk 靠谱得多。收拢配置的好处不只是省事。当配置只有一份时排查问题就变成了看这一份对不对而不是猜是哪份配置在起作用。这个思路上的转变比任何具体工具都重要。4.2 常见报错与排查速查表我把这一路踩过的坑整理成一张表遇到问题先对号入座能省不少时间。报错关键词可能原因排查方向node.js v24.21.0 is not yet released版本号不存在或版本管理器源有问题改用 LTS 版本检查版本管理器配置cc switch local proxy failed本地代理未运行或路由未覆盖 /responses检查代理进程、路由配置、实际请求路径model is not supported when using codex模型名与 Codex 期望不匹配核对模型标识符确认上游支持该接口your organization has disabled claude subscription账号组织权限限制联系管理员开启或改用个人账号codex 无法加载组织设置登录态或组织配置异常重新登录检查账号所属组织YAML 解析报错缩进用了 Tab 或冒号后缺空格用编辑器插件校验统一用空格缩进这张表里的每一条我基本都亲身遇到过。最想强调的是 YAML 缩进问题它出现的频率高到离谱而且报错信息往往指向一个和真实问题无关的行号让人误入歧途。养成用插件校验的习惯能砍掉一大半无效排查。4.3 代理层是排查的核心战场所有涉及多工具、多模型的方案代理层都是最容易出问题的地方也是排查时最该盯紧的地方。我的经验是给代理开详细日志把每个进来的请求路径、转发目标、响应状态都记下来。logging: level: debug format: json output: ./logs/proxy.log有了日志cc switch local proxy failed这类报错就不再是黑盒。你能清楚看到请求到底打到了哪个路径转发到了哪个上游上游返回了什么。我遇到过上游返回 200 但内容格式不对导致工具解析失败的情况光看工具报错完全摸不着头脑一看代理日志才发现是响应体结构不匹配。提示调试阶段把日志级别开到 debug问题解决后记得调回 info否则日志文件会迅速膨胀磁盘空间不知不觉就满了。5. 我在这套方案里踩过的真实坑5.1 环境变量污染导致的诡异行为有一次我明明在 openrig.yaml 里把端点改成了本地 LM Studio但 Claude Code 还是走了云端。排查了半天最后发现是.bashrc里还留着一行旧的export ANTHROPIC_BASE_URL它在启动脚本之前就生效了把 YAML 里的配置覆盖掉了。这个坑的教训是环境变量的优先级往往高于配置文件。当你改了配置却不生效时第一件事就是检查有没有残留的环境变量在捣乱。用env | grep -i anthropic之类的命令把相关变量全列出来逐个确认。5.2 版本不匹配引发的连锁反应Node.js 版本、Claude Code 版本、Codex 版本、代理工具版本这四个东西之间是有兼容性要求的。我有一次升级了 Node.js 到某个新版本结果 Claude Code 启动直接报错回退到 LTS 就正常了。所以我的建议是不要盲目追新。Node.js 用 LTS工具用稳定版升级之前先看 release notes 有没有 breaking change。尤其是团队协作场景大家的版本最好统一否则在我机器上能跑的经典问题就会反复上演。5.3 本地模型的性能预期管理用 LM Studio 跑本地模型接 Claude Code听起来很美好实际体验取决于你的硬件。我试过用本地模型处理一个中等规模的重构任务响应慢不说还经常理解偏。后来我调整了策略本地模型只用来做简单的代码解释、注释生成这类轻量任务复杂任务还是交给能力更强的模型。这个不是技术问题是预期管理问题。openrig 给了你灵活切换的能力但你要清楚每个模型适合干什么。把合适的任务交给合适的模型比追求全都本地化务实得多。5.4 配置文件放错位置的隐蔽性openrig 这类方案通常有约定的配置查找路径。我有一次把openrig.yaml放在了项目根目录但工具实际去用户主目录找结果配置完全没被读取工具用了默认值。这种问题特别隐蔽因为不报错只是行为不符合预期。排查方法很简单在配置里加一个明显的自定义值比如把端口设成一个不常见的数字然后看工具实际用的端口是不是这个值。如果不是说明配置没被读到去查查找路径。6. 给不同阶段使用者的实操建议6.1 刚上手的人先跑通单工具如果你刚开始接触 Claude Code 或 Codex别一上来就搞 openrig 这种多工具编排。先把单个工具跑通装好 Node.js装好 Claude Code能正常对话能读写文件。这一步稳了再去考虑接本地模型、接第三方端点。我见过太多人一上来就照着复杂教程配一堆东西结果某个环节出错根本不知道是哪一步的问题。单工具跑通是基线有了基线才能做对比排查。6.2 有多模型需求时再引入编排层当你确实需要在多个模型间切换或者团队需要统一配置时openrig 这套 YAML 驱动的编排才真正体现价值。这时候你已经有了单工具的经验理解每个配置项的作用引入编排层是水到渠成的事。引入的顺序我建议是先把手动切换的流程跑顺理解每一步在改什么然后再把这套流程抽象成 YAML 配置和切换命令。跳过手动阶段直接上自动化出了问题你会不知道自动化到底做了什么。6.3 团队协作要把配置纳入版本管理如果是团队使用openrig.yaml这类配置文件应该纳入 Git 管理但要注意脱敏。API key、账号信息这些绝对不能提交用环境变量或者单独的 secrets 文件管理并在.gitignore里排除。我的做法是仓库里放一份openrig.example.yaml作为模板每个人复制成openrig.yaml后填入自己的密钥。这样既保证了配置结构统一又避免了密钥泄露。新成员入职时照着模板填一遍就能跑起来省去大量沟通成本。6.4 定期清理和复盘配置配置这东西会随着时间累积垃圾。用不到的 provider、注释掉的旧端点、临时加的调试开关时间长了就变成一团乱麻。我养成的习惯是每个月过一遍配置文件把不用的删掉把含义不清的加上注释。这个习惯的价值在出问题时体现得最明显。一份干净、有注释的配置排查起来一目了然一份堆满历史遗留的配置光看懂就要半天。openrig 这类方案能不能长期用下去很大程度上取决于你有没有维护它的纪律。最后分享一个我一直在用的小技巧给每个 provider 起一个能一眼看懂的名字比如local-lmstudio-qwen而不是provider1。切换的时候不用去翻配置确认provider1到底是哪个模型直接看名字就知道。这种小细节看着不起眼但日积月累能省下大量来回确认的时间。