1. 从 openrig 说起一个把 Claude Code 和 Codex 拉到同一张桌子上的工具第一次看到openrig这个名字我下意识把它拆成了 “open” 和 “rig” 两截。rig 在工程语境里是“装配、搭台子”的意思比如把一堆设备 rig 起来跑测试。放到 AI 编码助手这个场景里openrig 干的事情其实非常直白把 Claude Code、Codex 这类命令行编码代理和本地模型、第三方 API、YAML 配置、Node.js 运行时这一整套东西装配成一个能稳定跑起来的工作台。我接触 Claude Code 和 Codex 的时间不算短踩过的坑也足够多。最开始是 Claude Code 在终端里直接执行命令、读写文件那种“代理真的在动我的项目”的感觉很上头后来 Codex CLI 出来配置风格、认证方式、模型接入逻辑又完全是另一套。再往后本地模型通过 LM Studio 跑起来想让它接进 Claude Code中间又冒出代理、端点、YAML 配置、Node.js 版本这一连串问题。openrig 这类工具出现的背景就是这些碎片化需求堆到一起之后大家需要一个统一的“装配层”。这篇文章适合谁看如果你正在折腾 Claude Code 安装、Codex 安装、Node.js 环境、YAML 配置文件或者想让 Claude Code 调用 LM Studio 的本地模型、用第三方 API 接入 DeepSeek、Qwen、GLM 这类模型那这篇内容基本覆盖了你 80% 的疑问。我会从整体设计思路讲到具体配置再到实际排查问题的过程尽量把每一步“为什么这么做”讲清楚而不是只丢一堆命令让你抄。需要先说明一点openrig 本身是一个相对轻量的装配思路不同人手里的实现细节会有差异。下面涉及的具体参数、目录结构、配置片段是基于我实际使用和常见社区实践整理出来的合理方案你在自己环境里落地时按实际情况微调即可。2. 整体设计思路为什么要把这些工具“rig”在一起2.1 核心矛盾编码代理的能力和接入方式高度碎片化Claude Code 和 Codex 虽然都是命令行编码代理但它们的设计哲学差别很大。Claude Code 更偏向“代理主动执行”它会在你的项目目录里读文件、改代码、跑命令交互方式接近一个坐在你旁边的工程师Codex CLI 则更强调配置驱动通过 YAML 或类似配置文件来定义模型、端点、行为参数。两者对模型来源的要求也不一样Claude Code 原生绑定 Anthropic 的模型体系Codex 则对 OpenAI 系模型更友好。问题就出在这里。当你想用本地模型比如 LM Studio 加载的模型或者第三方 APIDeepSeek、Qwen、GLM来驱动这些代理时每个工具都要单独配置一遍。Claude Code 要设环境变量、要处理端点兼容Codex 要改 YAML、要处理认证Node.js 版本不对还会直接报error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种让人一头雾水的错误。openrig 的价值就是把这些重复劳动收敛到一个装配层里。我自己的判断是与其在每个工具里各配一套不如抽象出一个中间层统一管理模型端点、认证信息、运行时版本和配置文件。这样 Claude Code 和 Codex 共享同一份“后端定义”切换模型时只改一处不用两边同步。这个思路和前端工程里把 API 请求收敛到统一 client 是一样的道理。2.2 方案选型为什么是 YAML Node.js 本地代理openrig 这类装配方案里YAML 和 Node.js 几乎是绕不开的两个基础件。YAML 负责声明式配置Node.js 负责运行时承载。为什么不用 JSON因为 YAML 支持注释、支持多行字符串、层级表达更自然写模型端点和代理规则时可读性明显更好。你在配置里写一段endpoint、model、api_key_env一眼就能看懂JSON 得靠脑补。Node.js 的角色更关键。Claude Code 和 Codex CLI 本身很多就是 Node.js 生态里的工具安装、升级、依赖管理都依赖 npm。Node.js 版本选不对轻则警告重则直接装不上。我实测下来LTS 版本比如 20.x 或 22.x是最稳的追最新版经常遇到“版本还没正式发布”的报错。openrig 把 Node.js 版本管理纳入装配范围本质上是在解决“工具链底座不稳”的问题。至于本地代理它的作用是做协议转换和端点转发。Claude Code 期望的请求格式和 LM Studio 或第三方 API 暴露的格式往往不完全一致中间加一层代理做适配比直接改工具源码现实得多。这也是为什么热词里会出现cc switch local proxy failed while handling codex endpoint /responses这类报错——代理层没配对请求就卡在中间了。2.3 装配层带来的三个实际收益第一个收益是配置集中。模型端点、密钥环境变量、超时参数、代理规则全部收在 YAML 里Claude Code 和 Codex 读同一份配置改一处两边生效。第二个收益是环境可复现。Node.js 版本、依赖版本、配置文件模板都固定下来换机器时按同一套流程走不会出现“我这边能跑你那边报错”。第三个收益是排查有抓手。出问题时你知道请求经过了哪几层工具 → 代理 → 模型端点逐层看日志就能定位而不是在一堆环境变量里瞎猜。提示装配层的核心不是“多装几个工具”而是把变量收敛。变量越少出问题时排查路径越短。3. 核心细节解析Node.js、YAML 与代理层的关键点3.1 Node.js 版本选择与安装避坑Node.js 是整套装配的地基但它的版本管理恰恰是最容易被忽视的环节。热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型症状你指定的版本号在官方源里还不存在或者你的包管理器索引没更新。我的做法是永远优先选 LTS 版本通过官方渠道下载安装包或使用版本管理工具切换。在 Windows 上直接去 Node.js 官网下载 LTS 的.msi安装包最省事安装时勾选“自动加入 PATH”。在 Ubuntu 上我更推荐用 NodeSource 的源或者版本管理工具避免系统自带的旧版本干扰。安装完第一件事是验证node -v npm -v两条命令都能正常输出版本号才算地基打好了。如果node -v报“command not found”说明 PATH 没配好如果版本号和你装的不一致说明系统里有多个 Node.js需要清理旧版本。我踩过的一个坑是用某个版本管理工具装了 Node.js但 Claude Code 是通过全局 npm 安装的结果切换 Node.js 版本后全局包全丢了Claude Code 直接消失。后来我养成习惯装完 Node.js 后统一用当前版本重新装一遍全局工具避免版本切换导致的“工具失踪”。3.2 YAML 配置文件的结构设计YAML 在 openrig 里承担的是“声明后端”的角色。一个典型的配置结构大概长这样providers: local_lmstudio: type: openai_compatible base_url: http://127.0.0.1:1234/v1 api_key_env: LMSTUDIO_KEY models: - qwen2.5-coder - deepseek-coder third_party: type: openai_compatible base_url: https://api.example.com/v1 api_key_env: THIRD_PARTY_KEY models: - deepseek-chat - glm-4 agents: claude_code: provider: local_lmstudio model: qwen2.5-coder codex: provider: third_party model: deepseek-chat这个结构的设计逻辑是providers定义“后端能力”agents定义“哪个代理用哪个后端”。这样切换模型时只改agents里的引用不用动providers。api_key_env指向环境变量而不是直接写密钥是为了避免密钥进版本库。YAML 最容易出错的地方是缩进。它用空格不用 Tab层级靠缩进表达。我见过太多人因为复制粘贴时混入 Tab导致解析直接失败。建议在编辑器里开启“显示空白字符”一眼就能看出 Tab 和空格的区别。另外字符串里的冒号、井号要加引号否则会被当成语法符号。3.3 本地代理层的职责与常见故障代理层是 openrig 里最“隐形”但也最容易出问题的部分。它的职责有三个协议适配、端点转发、请求日志。协议适配是把 Claude Code 或 Codex 发出的请求转换成目标模型端点能理解的格式端点转发是把请求送到正确的地址请求日志是出问题时唯一的排查依据。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错拆开看就是代理在处理 Codex 的/responses端点时失败了。可能原因有几个代理没启动、端点路径写错、目标模型不支持该端点格式、认证信息缺失。排查顺序应该是先确认代理进程在跑再用curl直接打目标端点看是否通最后看代理日志里请求和响应的具体内容。我的经验是代理层一定要开详细日志。没有日志的代理等于黑盒出问题只能靠猜。日志里重点看三样请求的 URL 路径、请求体里的 model 字段、响应状态码。这三样对上了基本就能定位问题在工具侧还是模型侧。4. 实操过程从零把 openrig 跑起来4.1 环境准备与 Node.js 安装第一步永远是环境。我以 Ubuntu 和 Windows 两个场景分别说。Ubuntu 下先更新包索引然后通过 NodeSource 源安装 LTScurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完验证node -v和npm -v。Windows 下直接去 Node.js 官网下载 LTS 的.msi双击安装勾选加入 PATH。装完打开新的终端窗口验证注意一定要开新窗口否则 PATH 不生效。Node.js 就绪后安装 Claude Code 和 Codex CLI。Claude Code 一般通过 npm 全局安装npm install -g anthropic-ai/claude-codeCodex CLI 同理按官方文档给的包名安装。安装过程中如果遇到权限错误Ubuntu 下不要无脑sudo先检查 npm 的全局目录权限Windows 下用管理员权限开终端。注意全局安装的工具依赖当前 Node.js 版本。如果你之后切换了 Node.js 版本记得重新安装这些全局工具。4.2 YAML 配置落地与参数填写环境好了之后创建配置目录。我习惯放在~/.openrig/下主配置文件叫config.yaml。按 3.2 节的结构填内容重点是把base_url和api_key_env填对。base_url要精确到/v1这一层很多 404 错误就是少写或多写了路径。密钥通过环境变量注入。在~/.bashrc或~/.zshrc里加export LMSTUDIO_KEYyour-local-key export THIRD_PARTY_KEYyour-third-party-key改完source一下让配置生效。验证环境变量是否生效echo $LMSTUDIO_KEY能打印出值就对了。这里有个细节LM Studio 本地服务通常不校验密钥但很多 OpenAI 兼容客户端要求api_key字段非空所以随便填一个占位值也行但别留空。4.3 启动本地模型与代理层LM Studio 里加载好模型后开启本地服务默认端口 1234。用curl验证端点是否通curl http://127.0.0.1:1234/v1/models能返回模型列表说明本地模型服务正常。然后启动代理层代理的启动方式取决于你用的具体实现常见的是通过 Node.js 脚本或独立二进制启动。启动后确认监听端口再用curl打代理端点看是否能正确转发到 LM Studio。这一步的关键是逐层验证。不要一上来就让 Claude Code 直接连先确认模型服务通再确认代理通最后才让工具连代理。逐层验证能把问题范围缩小到某一层排查效率高很多。4.4 让 Claude Code 和 Codex 接入配置Claude Code 接入时需要设置环境变量指向代理端点。常见做法是设ANTHROPIC_BASE_URL或对应的端点变量具体变量名以你使用的版本为准。设置后启动 Claude Code观察它是否能正常发起请求。如果报认证错误检查密钥环境变量如果报连接错误检查代理是否在跑。Codex 接入类似但它读 YAML 配置所以重点是确认 Codex 读的是你改的那份配置文件。热词里codex is ignoring 1 unrecognized configuration setting. check for typos or d这个警告就是配置项拼写错误或位置放错导致的。Codex 对配置项的层级和名称比较敏感改完配置后一定要看启动日志里有没有这类警告。两边都接上后做一次端到端测试在 Claude Code 里让它读一个文件在 Codex 里让它执行一个简单任务观察请求是否经过代理、模型是否正常响应。这一步跑通整套 openrig 就算装配完成了。5. 常见问题与排查技巧实录5.1 安装与版本类问题速查报错信息可能原因解决方向node.js v24.21.0 is not yet released指定了不存在的版本改用 LTS 版本更新包管理器索引command not found: nodePATH 未配置检查安装路径重开终端全局工具安装后消失切换了 Node.js 版本当前版本下重新全局安装npm install权限错误全局目录权限不足修正目录权限避免无脑 sudo这张表里的问题我基本都遇到过。最想强调的是版本问题不要追最新版LTS 是经过验证的稳定选择。很多人看到新版本号就想装结果踩一堆兼容性坑得不偿失。5.2 代理与端点类问题排查代理类问题的排查我总结成一个固定流程先看代理进程在不在再看代理日志有没有请求进来再看请求转发出去后目标端点返回什么。三步走完问题基本定位。cc switch local proxy failed while handling codex endpoint /responses这个报错按流程走代理进程在跑吗在。日志里有/responses请求吗有。转发到目标端点后返回什么如果返回 404说明目标端点不支持这个路径如果返回 400说明请求体格式不对如果返回 401说明认证有问题。对症下药就行。还有一个隐蔽的坑是端口冲突。代理默认端口如果被别的程序占了代理可能启动失败但你不一定注意到。启动后养成习惯确认监听端口lsof -i :端口号Windows 下用netstat -ano | findstr 端口号。端口被占就换一个别硬扛。5.3 配置类问题与独家避坑技巧YAML 配置类问题里缩进和拼写是两大元凶。我的做法是配置改完后先用解析器验证一遍python -c import yaml; yaml.safe_load(open(config.yaml))能正常解析说明语法没问题报错会直接告诉你哪一行有问题。这一步能省掉大量“配置看起来对但就是不生效”的排查时间。另一个技巧是配置分层。把不常改的providers和常改的agents分开甚至拆成两个文件用 YAML 的引用机制合并。这样切换模型时只动小文件降低改错概率。我见过有人把所有配置堆在一个大文件里改一个模型名结果缩进错了整个配置全废。最后一个独家经验保留一份能跑通的最小配置。当你折腾新模型、新端点把配置改乱时随时能回退到这份最小配置确认基础链路是通的。这份配置就是你的“安全网”比任何文档都管用。6. 关于模型接入与工具协同的一些个人体会Claude Code 调用 LM Studio 本地模型这个场景我实际跑下来最大的感受是本地模型的响应质量和云端模型有差距但胜在数据不出本地、成本可控。适合做代码补全、简单重构这类任务复杂推理还是得靠更强的模型。openrig 这类装配方案的好处就是让你能在本地模型和第三方 API 之间灵活切换按任务类型选后端。Codex 接入 DeepSeek、Qwen、GLM 这类第三方 API 时重点是确认 API 的兼容性。大部分第三方 API 都提供 OpenAI 兼容端点但细节上可能有差异比如流式响应格式、工具调用支持程度。遇到codex无法加载组织设置这类报错先确认认证信息是否正确再确认账号权限是否覆盖你要用的功能。VSCode 配置 Claude Code 和 Codex 也是常见需求。VSCode 里主要是通过终端集成来用这两个工具配置重点是把终端环境变量设对确保 VSCode 内置终端能读到你的配置。有时候系统终端能跑VSCode 终端报错就是环境变量没继承过去在 VSCode 设置里显式配置一下就好。这套东西折腾下来我的核心建议是先把最小链路跑通再逐步加复杂度。不要一上来就本地模型、第三方 API、代理、多工具全上那样出问题你根本不知道是哪一层。先让 Claude Code 连上一个最简单的端点跑通再加代理再加 Codex一层一层来。每加一层验证一次问题永远只可能在新加的那层排查范围极小。最后分享一个小技巧给每个工具和代理都开独立日志文件日志里带上时间戳和请求 ID。出问题时按时间戳对齐各层日志请求从工具到代理到模型的完整路径一目了然。这个习惯帮我省了无数排查时间比任何调试工具都实在。