1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟 rig 这个词在英文里常指“装备、装置”。但翻了一圈社区讨论和仓库结构之后才反应过来它其实是围绕 AI 编程助手生态做的一套配置编排方案核心解决的是 Claude Code、Codex 这类命令行智能体在本地环境里“装得上、连得通、切得快”的问题。说白了openrig 不是某个单一工具而是一层把 Node.js 运行时、YAML 配置、模型端点、代理转发串起来的胶水层。为什么会有这么个东西存在因为现在用 AI 编程助手的人越来越多但真正卡住大家的往往不是模型能力而是环境。你装 Claude Code 要 Node.js装 Codex 也要 Node.js两个工具对 Node 版本的要求还不一定一致你想让它们调用本地模型或者第三方端点就得改配置配置格式又是 YAML缩进错一个空格就报错。openrig 想做的就是把这些零碎环节收敛成一套可复用的编排逻辑让你换模型、换工具、换机器的时候不用从头再来。它适合谁我觉得三类人最需要一是刚接触 Claude Code 或 Codex、被安装步骤劝退的新手二是同时用多个 AI 编程工具、需要频繁切换模型端点的进阶用户三是在团队里负责统一开发环境、想让同事开箱即用的工程负责人。如果你只是偶尔用网页版聊天那 openrig 对你意义不大但只要你打算把 AI 助手真正嵌进日常编码流程这套东西迟早会碰到。我自己的判断是openrig 的价值不在于它发明了什么新技术而在于它把一堆散落的实践固化成了结构。Node.js 是底座YAML 是描述语言Claude Code 和 Codex 是上层应用openrig 是中间那层“让它们别打架”的调度层。理解这个定位后面所有配置和排查都会顺很多。2. 核心思路拆解为什么是 Node.js YAML 这套组合2.1 Node.js 作为运行时底座的原因Claude Code 和 Codex 的 CLI 版本基本都是 Node.js 生态的产物这不是偶然。Node.js 的包管理机制让工具分发变得极其简单一条 npm 命令就能把整个 CLI 装到全局跨平台一致性也比较好。你在 Windows、macOS、Ubuntu 上装 Node.js 之后后续的 Claude Code 安装、Codex 安装流程几乎一模一样这对社区教程的传播非常友好。但 Node.js 也带来一个经典痛点版本碎片化。我见过太多人卡在error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错上本质是版本号写错了或者源里还没有这个版本。还有人装了 Node.js 之后 Claude Code 能跑、Codex 报错或者反过来原因往往是某个工具依赖的 Node 版本区间不同。openrig 的思路是用 YAML 把 Node 版本要求显式声明出来而不是靠口头约定“你装个 LTS 就行”。提示Node.js 官网下载页面有 LTS 和 Current 两个通道生产环境优先选 LTSCurrent 版本虽然新但生态兼容性偶尔会出问题。2.2 YAML 承担配置描述角色的逻辑为什么不用 JSON 或者 TOMLJSON 写起来太啰嗦不能写注释配置一长就没法维护TOML 虽然友好但嵌套表达能力弱一些。YAML 的优势在于层级清晰、支持注释、适合描述“环境-工具-模型”这种多层结构。openrig 用 YAML 来定义每个 rig 的组成比如用哪个 Node 版本、装哪些 CLI、每个 CLI 指向哪个模型端点、走不走本地代理。YAML 的坑也很集中缩进必须用空格不能用 Tab冒号后面要留空格字符串里的特殊字符要引号包裹。我踩过最典型的一次是cc switch local proxy failed while handling codex endpoint /responses这个报错排查半天发现是 YAML 里 endpoint 的 URL 少写了一个斜杠导致代理转发时路径拼接错误。这种问题不看配置根本想不到。2.3 把 Claude Code 和 Codex 放在同一套编排里的考量单独用 Claude Code 或者单独用 Codex其实不需要 openrig 这么一层。真正需要编排的场景是你白天用 Claude Code 写业务代码晚上用 Codex 跑一些批量重构两个工具想共用同一套模型端点配置或者你想在两者之间快速切换本地模型和云端模型。openrig 把这种切换抽象成 YAML 里的一个字段改一行配置就能换端点不用去翻每个工具各自的配置文件。这里有个设计取舍值得说openrig 没有做成一个常驻服务而是做成配置生成加环境检查的组合。常驻服务虽然切换更丝滑但会引入额外的进程管理和端口占用问题对只想安安静静写代码的人来说反而是负担。配置生成的方式更轻代价是每次切换要重新应用一次配置但换来的是可审计、可版本控制。3. 环境准备Node.js 与 YAML 的安装细节3.1 Node.js 安装的版本选择与验证不管你用哪个系统第一步都是把 Node.js 装对。Windows 用户直接去 Node.js 官网下载 LTS 的 msi 安装包一路下一步就行安装时记得勾选“Add to PATH”否则后面命令行里找不到 node 命令。Ubuntu 用户我更推荐用 NodeSource 的源来装比系统自带的版本新命令大致是这样curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs装完之后必须验证别装完就往下走node -v npm -v两个命令都要有输出且 node 版本建议在 18 以上。如果node -v报“command not found”说明 PATH 没配好Windows 重启终端或者手动加环境变量Ubuntu 检查/usr/bin/node是否存在。注意不要同时装多个来源的 Node.js比如系统 apt 装了一个、nvm 又装了一个很容易出现node -v和实际运行版本不一致的诡异问题。选定一种方式就坚持用。3.2 YAML 环境的理解与工具准备严格来说 YAML 不是需要“安装”的东西它是一种文件格式。但很多人搜“yaml安装”其实是想要一个能校验 YAML 的工具。我的建议是装一个yaml的 npm 包做命令行校验或者直接在 VS Code 里装 YAML 插件写的时候就有缩进高亮和错误提示。npm install -g yaml装完之后可以用它来检查配置文件语法yaml openrig.yaml如果文件有问题会直接报出行号和原因比肉眼一行行看快得多。VS Code 里我常用的是 Red Hat 出的 YAML 插件它对 Claude Code 配置、Codex 配置这类文件的 schema 支持比较好能提前发现字段名写错的问题。3.3 目录结构规划让配置有地方放openrig 的配置不建议散落在用户目录各处。我习惯在项目根目录或者用户主目录下建一个统一的.openrig文件夹里面放openrig.yaml主配置和profiles/子目录存不同场景的配置片段。这样切换场景时只需要换 profile 引用不用改主文件。~/.openrig/ ├── openrig.yaml ├── profiles/ │ ├── claude-local.yaml │ ├── codex-cloud.yaml │ └── shared-endpoints.yaml └── logs/这个结构的好处是端点定义可以抽到shared-endpoints.yaml里复用Claude Code 和 Codex 引用同一份端点配置改一处两边都生效。日志目录留着排查cc switch local proxy failed这类问题时看转发记录。4. openrig.yaml 配置文件的完整写法4.1 主配置文件的结构设计一份能跑的 openrig.yaml 大致分四块runtime 定义运行时、tools 定义要装的 CLI、endpoints 定义模型端点、profiles 定义场景组合。我下面给一份可以直接抄的模板字段名按常见实践来你根据自己实际情况改值。runtime: node: 18.0.0 packageManager: npm tools: claude-code: enabled: true package: anthropic-ai/claude-code endpoint: local-qwen codex: enabled: true package: codex-cli endpoint: cloud-deepseek endpoints: local-qwen: baseUrl: http://127.0.0.1:1234/v1 model: qwen2.5-coder apiKey: local cloud-deepseek: baseUrl: https://api.deepseek.com/v1 model: deepseek-coder apiKey: ${DEEPSEEK_API_KEY} profiles: default: tools: - claude-code - codex这里有几个设计点要解释。runtime.node用语义化版本区间而不是固定版本是为了兼容不同机器上已有的 NodeapiKey用${}引用环境变量而不是写死避免密钥进版本库endpoints抽出来单独定义是为了让多个工具共享。4.2 端点配置与模型切换的关键字段端点这块是 openrig 最核心也最容易出错的地方。baseUrl必须指向兼容 OpenAI 接口格式的服务因为 Claude Code 和 Codex 底层大多按这个格式发请求。本地模型比如通过 LM Studio 起的服务默认端口常见是 1234路径是/v1少写这个/v1就会出现 404 或者endpoint /responses找不到的问题。model字段要和服务端实际加载的模型名完全一致大小写都不能错。我见过有人本地加载的是Qwen2.5-Coder-7B配置里写qwen2.5-coder结果请求发过去服务端不认报模型不存在。最稳妥的办法是先 curl 一下服务端的模型列表接口确认名字curl http://127.0.0.1:1234/v1/models返回的id字段是什么配置里就写什么。4.3 用 profile 实现 Claude Code 与 Codex 的快速切换profile 的意义在于把“工具组合 端点组合”打包成一个可切换的单元。比如你有一个localprofile 全部指向本地模型一个cloudprofile 指向云端端点切换时只需要改主配置里activeProfile的值或者用命令行参数指定。activeProfile: local profiles: local: tools: [claude-code, codex] endpoints: claude-code: local-qwen codex: local-qwen cloud: tools: [claude-code, codex] endpoints: claude-code: cloud-deepseek codex: cloud-deepseek这种写法的好处是切换粒度可控你可以让 Claude Code 走本地、Codex 走云端也可以两个都走同一个端点。实际用下来本地模型响应快但能力有限云端模型能力强但有延迟和成本混着用是最务实的。5. 实操过程从零到跑通一次完整切换5.1 安装 Claude Code 与 Codex 的实操步骤Node.js 就绪之后装 Claude Code 和 Codex 都是 npm 全局安装。Claude Code 的包名按官方文档来Codex 的 CLI 包名社区里有几个变体装之前最好确认一下当前维护的版本。npm install -g anthropic-ai/claude-code npm install -g codex-cli装完分别验证claude --version codex --version如果claude命令找不到检查 npm 全局 bin 目录是否在 PATH 里。Windows 上通常是%APPDATA%\npmUbuntu 上是/usr/local/bin或~/.npm-global/bin。这一步卡住的人特别多本质都是 PATH 问题不是安装失败。提示如果你在 VS Code 里用 Claude Code装完 CLI 之后还要在 VS Code 里装对应扩展然后在设置里指向 CLI 路径。VS Code 配置 Claude Code 时最容易漏的就是这个路径设置。5.2 应用 openrig 配置并验证端点连通性配置写完之后不要急着启动工具先做连通性验证。用 curl 打一下端点确认能返回模型列表curl -s http://127.0.0.1:1234/v1/models | head -20能返回 JSON 且里面有模型 id说明端点本身没问题。然后再验证 API key 是否生效云端端点可以发一个最小的 chat 请求curl -s https://api.deepseek.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-coder,messages:[{role:user,content:hi}]}这一步能通后面工具里基本不会因为端点问题报错。如果这一步就失败问题在端点或密钥跟 openrig 和工具本身无关排查范围一下子缩小了。5.3 切换过程中的现场记录与观察我第一次做本地到云端的切换时记录了几个关键观察点。切换后 Claude Code 首次请求会有明显延迟因为要重新建立连接和加载模型上下文Codex 在切换端点后如果报the gpt-5.6-sol model is not supported说明配置里模型名还是旧的没跟着端点一起换。这个报错信息其实很明确就是模型名和端点不匹配。另一个观察是代理层。如果你用了 cc switch 这类本地代理来做端点转发切换时要确认代理进程有没有重启。我遇到过代理没重启、配置改了但请求还走旧端点的情况表现为改了配置没效果。后来养成习惯每次切换后先看代理日志确认请求打到了哪个端点。tail -f ~/.openrig/logs/proxy.log日志里能看到实际转发的 URL 和模型名比猜靠谱得多。6. 常见报错与排查速查6.1 安装类报错的处理思路安装阶段最高频的就是 Node 版本相关报错。error installing 24.21.0: node.js v24.21.0 is not yet released这种要么是版本号写错要么是源同步延迟换成 LTS 版本基本能解决。还有your organization has disabled claude subscription access这类属于账号权限层面不是本地环境问题需要去账号设置里确认订阅状态。报错关键词可能原因处理方向node.js vXX is not yet released版本号不存在或源未同步改用 LTS 版本command not found: claudenpm 全局 bin 不在 PATH检查并添加 PATHorganization has disabled access账号订阅权限问题检查账号订阅状态codex无法加载组织设置配置文件路径或权限检查配置目录读写权限6.2 端点与代理类报错的定位方法cc switch local proxy failed while handling codex endpoint /responses这个报错我遇到不止一次根因通常是三类端点 URL 拼错、代理进程没起来、模型名不匹配。定位顺序建议是先 curl 直连端点通了再查代理代理通了再查工具配置。一层层排除比一上来就改配置高效。还有一个隐蔽的坑是端口占用。本地模型服务默认端口如果被别的进程占了服务起不来但报错不明显表现为连接被拒绝。用lsof -i :1234或者 Windows 的netstat -ano | findstr 1234确认端口状态。6.3 模型调用类报错的应对模型调用阶段的报错往往和配置字段强相关。model is not supported是模型名不对401 unauthorized是密钥问题404 not found多半是 baseUrl 路径少了/v1。这几个报错信息都很直白对着配置逐字段核对就行。我整理了一个排查顺序实测下来能覆盖八成问题先确认 Node 版本再确认 CLI 能启动再 curl 端点再看代理日志最后核对模型名和密钥。这个顺序是从底层往上层走避免在错误的层面上浪费时间。注意改完配置后一定要重新加载很多工具不会自动监听配置文件变化。Claude Code 和 Codex 都需要重启会话才能读到新配置。7. 我踩过的坑和几条实用经验配置文件的编码问题值得单独说。YAML 对 UTF-8 有要求如果你在 Windows 上用记事本编辑偶尔会存成带 BOM 的 UTF-8导致解析时报奇怪的字符错误。我现在的习惯是统一用 VS Code 编辑右下角确认编码是 UTF-8 无 BOM。环境变量注入的时机也容易出问题。${DEEPSEEK_API_KEY}这种引用要求启动工具的那个 shell 里确实有这个变量。如果你在 A 终端 export 了变量在 B 终端启动工具是读不到的。要么写进 shell 的启动脚本要么在同一个终端里操作。还有一点是关于本地模型的选择。不是所有本地模型都适合做代码助手有些模型对工具调用格式支持不好接进 Claude Code 或 Codex 之后会频繁报解析错误。选模型时优先挑明确支持 function calling 的版本能省掉大量调试时间。最后分享一个我常用的验证小技巧配置改完之后先用一个最简单的 prompt 跑一次比如让它输出当前目录的文件列表。这个请求链路短、依赖少能快速验证“配置-端点-模型”整条链路是否通畅。链路通了再去跑复杂任务排查成本低很多。这套流程用熟之后换机器、换模型、换工具基本十分钟内能搞定比每次从头查文档快得多。