1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里常指设备支架、测试台架。翻了一圈社区讨论和仓库结构才反应过来它其实是围绕 AI 编程助手做的一套本地化编排与配置工具核心解决的是 Claude Code、Codex 这类命令行智能体在真实开发环境里装得上、连得通、切得快、管得住的问题。热词里那一串 claude code 安装、codex 安装教程、cc switch local proxy failed、yaml 文件怎么创建基本就是它要覆盖的痛点地图。说白了openrig 想干的事情是把多个 AI 编程助手的接入配置、模型端点切换、本地代理转发、项目级 YAML 声明统一收拢到一套可版本管理的结构里。你不用再手动改一堆环境变量也不用在 Claude Code 和 Codex 之间反复卸载重装更不用为了接一个本地模型去翻半天文档。它适合三类人一是刚接触 Claude Code、Codex 想快速跑通的新手二是同时用多个模型端点、需要频繁切换的老手三是团队里想把 AI 助手配置标准化、避免每个人环境不一致的工程负责人。我自己的使用场景比较典型白天用 Claude Code 处理重构和代码审查晚上用 Codex 跑批量脚本生成中间还要切到本地 LM Studio 的模型做离线实验。以前每次切换都要改配置文件、重启终端偶尔还会遇到cc switch local proxy failed while handling codex endpoint /responses这种报错排查起来很烦。openrig 的价值就在于把这些切换动作声明化、可复现化让换模型变成改一行 YAML 的事。2. 整体设计思路与方案选型拆解2.1 为什么用 YAML 做配置中枢openrig 选择 YAML 作为配置载体这个决定我认为非常务实。对比 JSONYAML 支持注释这对需要写为什么这么配的团队场景太重要了对比 TOMLYAML 的嵌套结构表达多层级配置更自然比如一个 provider 下面挂多个 model、每个 model 又有自己的参数。热词里yolov10 yaml 文件怎么创建rstudio 的 yaml 在哪里其实反映了一个普遍现象YAML 已经成了各类工具的事实标准配置格式用户学习成本被摊薄了。openrig 的 YAML 结构大致分三层顶层是全局设置中间是 provider 列表底层是每个 provider 下的模型与端点。这样设计的好处是切换模型时只动最底层不会影响全局行为。我见过不少人把所有配置平铺成一层结果改一个端点要翻几十行很容易改错。提示YAML 对缩进极其敏感建议统一用两个空格绝对不要混用 Tab。我踩过的坑是用编辑器自动格式化后缩进变成四个空格整个配置直接解析失败报错信息还特别隐晦。2.2 Node.js 作为运行时底座的原因openrig 依赖 Node.js 运行热词里node.js 安装node.js 是干什么的node.js lts 下载高频出现说明很多用户卡在第一步。选 Node.js 的理由很直接Claude Code 和 Codex 的 CLI 本身都是 Node 生态的产物openrig 作为编排层用同生态能最大程度减少依赖冲突。而且 Node.js 的跨平台支持成熟Windows、macOS、Ubuntu 都能跑热词里claude code windowsubuntu 配置 claude code正好对应这些平台。版本选择上我强烈建议用 LTS 版本。热词里有个报错很典型error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这就是版本号写错或者用了未发布版本导致的。LTS 版本经过长期验证和各类 CLI 工具的兼容性最好。截至我写这篇内容时Node.js 20.x 和 22.x 的 LTS 都是稳妥选择。2.3 本地代理转发的设计考量openrig 里最容易被忽视但最关键的一环是本地代理转发。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错本质是代理层在转发 Codex 的/responses端点时出了问题。为什么需要代理因为不同 AI 助手的 API 协议格式不完全一致Claude Code 和 Codex 对请求体、响应体的字段要求有差异代理层要做协议适配和字段映射。openrig 把代理做成可配置的你可以指定监听端口、目标端点、超时时间、重试策略。这个设计的好处是当某个端点不稳定时你可以在代理层加重试和降级逻辑而不用改上层助手的代码。我实测下来给代理加一个 30 秒超时和两次重试能解决大部分偶发的连接失败。3. 核心细节解析与实操要点3.1 环境准备Node.js 与包管理器的正确装法第一步永远是环境。Windows 用户直接去 Node.js 官网下载 LTS 安装包安装时勾选Add to PATH这一步漏了后面所有命令都会提示找不到。macOS 用户我建议用 nvm 管理版本因为不同项目可能依赖不同 Node 版本nvm 切换起来干净。Ubuntu 用户可以用 NodeSource 的源安装比系统自带的版本新。装完之后验证三件事node -v看版本、npm -v看包管理器、npx -v看执行器。三个都正常输出才算环境就绪。我遇到过 npm 正常但 npx 报错的情况最后发现是 PATH 里有两个 Node 安装路径冲突清理掉旧的就好了。注意如果你之前装过旧版 Node.js务必先卸载干净再装新版。残留的全局包和缓存会导致各种诡异问题比如codex 无法加载组织设置这类报错有时候根源就是环境不干净。3.2 openrig 的安装与初始化openrig 的安装走 npm 全局安装即可命令是npm install -g openrig。装完后运行openrig init会在当前目录生成一个默认的 YAML 配置文件。这个初始化动作很关键它会根据你系统里已安装的 Claude Code、Codex 自动探测可用配置生成一份能直接跑的模板。初始化后你会看到一个类似这样的结构version: 1 providers: - name: claude-code type: claude endpoint: https://api.anthropic.com models: - name: claude-sonnet id: claude-sonnet-4-20250514 - name: codex type: openai endpoint: https://api.openai.com/v1 models: - name: gpt-codex id: gpt-5.6-sol proxy: port: 8787 timeout: 30000 retries: 2这份配置里providers是核心proxy是转发层。我建议新手先不要改结构只改 endpoint 和 model id跑通之后再动其他。3.3 模型端点的接入与切换逻辑openrig 最实用的功能是模型切换。热词里claude code 调用 lmstudio 的本地模型codex 接入 deepseek使用 cc switch 接入 deepseek v4, qwen, glm 等模型都指向这个需求。切换的本质是改 YAML 里对应 provider 的 endpoint 和 model id然后让 openrig 重新加载配置。以接入本地 LM Studio 为例LM Studio 默认在http://localhost:1234/v1提供 OpenAI 兼容接口。你只需要在 YAML 里加一个 provider- name: lmstudio-local type: openai endpoint: http://localhost:1234/v1 models: - name: local-qwen id: qwen2.5-coder-7b然后在 Claude Code 或 Codex 的配置里把 base URL 指向 openrig 的代理端口由 openrig 负责转发到 LM Studio。这样切换模型时上层助手完全无感只认 openrig 的代理地址。提示本地模型的上下文窗口通常比云端小接入前先确认模型的 max context 参数否则长对话会突然截断排查起来很费时间。3.4 YAML 配置的常见写法与校验YAML 写错是新手最高频的问题。我整理了几个必查点缩进是否统一、冒号后是否有空格、字符串是否需要引号、列表项是否用短横线开头。openrig 提供了openrig validate命令能在启动前校验配置合法性这个命令一定要养成习惯跑。另外YAML 里如果值包含特殊字符比如 URL 里的冒号、问号建议用引号包起来避免解析歧义。我见过有人 endpoint 写成http://localhost:1234/v1没加引号结果 YAML 把冒号当成了键值分隔符直接报错。4. 实操过程与核心环节实现4.1 从零到跑通的完整流程我把整个流程拆成六步按顺序做基本不会出错。第一步装 Node.js LTS验证node -v、npm -v、npx -v三个命令。第二步全局安装 openrig运行openrig init生成配置。第三步编辑 YAML填入你要用的 provider 和 model。第四步运行openrig validate校验配置。第五步启动代理openrig start确认端口监听正常。第六步在 Claude Code 或 Codex 里把 base URL 指向代理地址发一条测试消息验证链路。这六步里第三步和第六步最容易出问题。第三步的问题通常是 YAML 语法第六步的问题通常是端点地址写错或者代理没启动。4.2 代理启动与端口配置的细节openrig 默认代理端口是 8787这个端口可以改。改端口时要注意两点一是别和系统里已占用的端口冲突二是改完之后上层助手的 base URL 也要同步改。我建议用netstat或lsof先查一下端口占用情况。启动代理后openrig 会输出监听日志。如果看到listening on 0.0.0.0:8787就说明成功了。如果看到EADDRINUSE就是端口被占换个端口即可。代理启动后建议先用 curl 测一下curl http://localhost:8787/v1/models能返回模型列表就说明代理层工作正常。这一步能帮你把问题范围缩小到代理层还是上层助手。4.3 多模型切换的实操演示假设你配置了三个 providerclaude-code、codex、lmstudio-local。切换时只需要改上层助手指向的代理路径或者在 openrig 里设置默认 provider。openrig 支持通过环境变量OPENRIG_PROVIDER指定当前激活的 provider这样切换就是改一个环境变量的事。我实测下来最顺手的做法是给每个 provider 配一个独立的代理端口比如 claude 走 8787、codex 走 8788、本地模型走 8789。这样上层助手各连各的互不干扰切换时连环境变量都不用改。代价是占用几个端口但对本地开发来说完全不是问题。4.4 参数计算与超时设置代理的超时和重试参数需要根据实际网络情况调。我的经验值是云端 API 超时设 30 秒、重试 2 次本地模型超时设 60 秒、重试 1 次。因为本地模型首次加载可能较慢超时设太短会误判为失败。重试策略上openrig 支持指数退避。开启后第一次重试等 1 秒第二次等 2 秒第三次等 4 秒。这个策略对偶发的网络抖动很有效但如果是端点本身不可用重试只会浪费时间。所以重试次数别设太多2 到 3 次足够。5. 常见问题与排查技巧实录5.1 高频报错速查表报错信息可能原因解决方向cc switch local proxy failed while handling codex endpoint /responses代理层协议映射错误或端点不可达检查代理日志确认 Codex 端点地址和字段映射error installing 24.21.0: node.js v24.21.0 is not yet releasedNode 版本号写错或用了未发布版本改用 LTS 版本号your organization has disabled claude subscription access账号权限或订阅状态问题检查账号订阅状态确认组织策略codex 无法加载组织设置环境残留或配置冲突清理旧配置重新初始化YAML 解析失败缩进、冒号、引号问题跑openrig validate逐行检查代理启动报EADDRINUSE端口被占用换端口或释放占用进程5.2 代理转发失败的排查思路代理转发失败是最常见也最烦的问题。我的排查顺序是先看 openrig 日志有没有收到请求再看请求有没有转发出去最后看响应有没有回来。如果日志里连请求都没收到说明上层助手的 base URL 配错了如果收到了但转发失败说明目标端点不可达如果转发成功但响应异常说明协议映射有问题。热词里那个/responses端点的报错我遇到过几次基本都是 Codex 的请求体字段和代理期望的不一致导致的。解决办法是在 openrig 的 YAML 里给对应 provider 加一个字段映射配置把 Codex 的字段名映射成目标端点认识的字段名。5.3 环境隔离与版本冲突的处理同时装 Claude Code 和 Codex 时两者可能依赖不同版本的 Node 或不同的全局包容易冲突。我的做法是用 nvm 给每个工具配独立的 Node 版本或者用容器隔离。如果不想搞太复杂至少保证全局包不冲突装之前先npm ls -g --depth0看一眼已装的全局包。注意不要在同一台机器上同时跑多个版本的 openrig 全局安装npm install -g会覆盖旧版本但残留的配置可能还在导致行为诡异。升级前先npm uninstall -g openrig再装。5.4 独家避坑经验第一个坑YAML 里注释别写中文标点某些解析器对中文标点敏感容易报错。第二个坑代理端口别用 8080、3000 这些常用端口冲突概率高。第三个坑本地模型接入时先确认模型服务本身能通再配 openrig否则问题会混在一起。第四个坑切换 provider 后记得重启上层助手有些助手会缓存 base URL。我踩过最深的坑是配置文件路径问题。openrig 默认读当前目录的配置但如果你在别的目录启动它会读不到。解决办法是用--config参数显式指定配置路径或者养成在项目根目录启动的习惯。6. 工具选型与扩展玩法6.1 Claude Code 与 Codex 的取舍这两个工具定位有差异。Claude Code 在代码理解和重构上更强适合处理复杂逻辑Codex 在批量生成和脚本编写上更顺手。我的用法是两者都装通过 openrig 统一管理按任务类型切换。热词里claude code 使用codex 使用教程高频出现说明很多人还在选型阶段我的建议是别纠结先都跑通用一周自然就知道哪个更适合自己。6.2 VS Code 集成配置热词里vscode 配置 claude codeclaude code for vs codevscode 接入 claude code说明很多人想在编辑器里直接用。VS Code 集成的方式是在设置里配置终端环境变量把 base URL 指向 openrig 代理。这样在 VS Code 终端里跑 Claude Code 或 Codex自动走 openrig 的配置不用每次手动设。6.3 后续可扩展的方向openrig 的 YAML 结构是开放的你可以往里加自定义字段比如给每个 provider 加标签、加优先级、加限流配置。我目前加了一个tags字段用来标记 provider 的用途切换时按标签筛选比记名字方便。另外openrig 的代理层可以挂日志中间件把每次请求的耗时、token 数记下来方便做成本分析。这个内容后续还可以这样扩展把 openrig 的配置纳入 Git 管理团队共享一份基础配置个人用本地覆盖文件做差异化。这样既保证团队一致性又保留个人灵活性。我在实际使用中发现配置文件进版本库之后新人上手时间从半天缩短到十分钟这个收益比想象中大。