1. 从“openrig”说起一个把 Claude Code 和 Codex 装进同一副骨架的思路第一次看到 “openrig” 这个词我脑子里蹦出来的画面是摄影棚里的那套金属支架——灯、相机、麦克风、反光板全都能挂上去接口统一随时换件。后来发现这个理解方向基本没错openrig 想干的事就是给当下这波命令行 AI 编程工具做一副“通用支架”让 Claude Code、Codex 这类工具能共用一套配置、一套模型接入方式、一套工作流而不是每换一个工具就重装一遍环境、重写一遍配置。如果你最近在折腾 Claude Code 或者 Codex大概率踩过这些坑装 Node.js 版本不对、YAML 配置文件不知道写在哪、想接本地模型或者第三方 API 结果报一堆 endpoint 错误、Windows 和 Ubuntu 上表现还不一样。openrig 这类项目的价值就在于把这些零散的、每个工具各搞一套的东西收敛成一份可复用的骨架。它解决的不是“某个模型好不好用”的问题而是“我怎么让多个 AI 编程工具在同一台机器上和平共处、共享配置”的问题。这篇内容适合三类人看一是刚接触 Claude Code、Codex连 Node.js 和 YAML 都还没搞明白的新手二是已经在用但被多工具配置冲突、模型接入报错折腾得够呛的进阶用户三是想自己搭一套统一 AI 编程环境、甚至想基于 openrig 思路做二次开发的人。我会从整体设计思路讲到具体配置再到实际踩坑排查尽量把每一步的“为什么”说清楚让你看完能直接照着搭一套自己的环境。2. openrig 的整体设计与选型逻辑2.1 为什么需要一层“支架”而不是直接用官方工具Claude Code 和 Codex 本质上都是命令行里的 AI 编程助手它们的工作方式类似读取你的项目上下文调用背后的模型返回代码修改建议或者直接执行命令。问题在于这两个工具各自有独立的安装方式、独立的配置文件、独立的模型接入逻辑。Claude Code 走的是 Anthropic 的订阅体系Codex 走的是 OpenAI 的体系你想让它们都接同一个第三方模型或者本地模型就得分别改两套配置。openrig 的核心思路是抽象出一层中间层。这层中间层负责几件事统一管理模型接入端点、统一管理工具的运行参数、统一处理不同工具之间的配置差异。你可以把它理解成一个“配置翻译器”——你只写一份模型接入信息openrig 负责把它翻译成 Claude Code 能读的格式和 Codex 能读的格式。这种设计的好处很直接。第一换模型的时候只改一处不用两个工具各改一遍。第二新增工具的时候只要 openrig 支持接入成本大幅降低。第三配置集中管理之后排查问题会容易很多因为你知道问题大概率出在中间层或者某个工具的适配层而不是散落在系统各处的十几个文件里。提示openrig 这类项目目前多处于早期阶段接口和配置格式可能变动较快。建议在正式用于生产环境前先在一个独立目录或者容器里跑通全流程确认稳定后再迁移到主力开发环境。2.2 技术栈选型Node.js、YAML 与 CLI 的组合逻辑openrig 以及它要托管的 Claude Code、Codex基本都是 Node.js 生态的产物。这不是偶然。Node.js 在命令行工具领域有天然优势npm 生态成熟、跨平台支持好、启动速度对于 CLI 场景够用。Claude Code 和 Codex 的安装包本质上都是 npm 包所以你的机器上必须先有 Node.js而且版本不能太老。这里有个很多人踩过的坑Node.js 版本报错。热词里出现的 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型症状——你照着某个教程敲了安装命令结果那个版本号根本不存在或者还没发布。Node.js 的版本号是有规律的偶数版本是 LTS长期支持版奇数版本是当前版。对于 openrig 这种要长期跑的环境我建议直接用 LTS 版本比如 20.x 或者 22.x别去追最新的奇数版。YAML 的选择也很好理解。JSON 写配置太啰嗦不支持注释多行字符串处理起来难受。YAML 天生适合写配置文件层级清晰、支持注释、可读性好。openrig 用 YAML 来定义模型端点、工具参数、路由规则这些东西你打开配置文件一眼就能看懂在配什么。代价是 YAML 对缩进极其敏感多一个空格少一个空格都可能让整个配置解析失败这是新手最容易翻车的地方。2.3 模型接入的抽象层设计openrig 最核心的部分是模型接入抽象层。Claude Code 默认走 Anthropic 的 APICodex 默认走 OpenAI 的 API但很多人想接第三方模型或者本地模型比如通过 LM Studio 跑的本地模型或者各种兼容 OpenAI 接口的第三方服务。这时候问题就来了不同工具的 API 路径不一样请求格式有差异认证方式也不同。openrig 的做法是定义一个统一的模型端点描述然后针对每个工具写适配器。比如你定义一个端点叫 “local-qwen”指向本地的某个服务地址openrig 会负责把这个端点转换成 Claude Code 需要的格式和 Codex 需要的格式。热词里那个 “cc switch local proxy failed while handling codex endpoint /responses” 报错本质上就是适配层在处理 Codex 的 /responses 端点时出了问题——可能是路径拼接错了可能是请求头没带对也可能是目标服务根本不支持那个端点格式。理解这一层的关键在于AI 编程工具和模型服务之间的通信本质上就是 HTTP 请求。工具把上下文打包成特定格式发出去模型服务返回结果。openrig 要做的就是确保这个打包和解析过程在不同工具之间正确切换。3. 环境搭建Node.js、YAML 与工具安装的实操细节3.1 Node.js 安装版本选择与常见报错处理装 Node.js 这件事看起来简单但热词里一堆相关搜索说明翻车的人不少。我先把最稳的路径说清楚。Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包双击安装一路下一步。安装完成后打开 PowerShell 或者 CMD输入node -v和npm -v能正常输出版本号就说明装好了。注意不要用太老的版本Claude Code 和 Codex 对 Node.js 版本有最低要求一般建议 18 以上稳妥起见用 20 LTS 或 22 LTS。Ubuntu 用户我强烈建议用 NodeSource 的仓库来装而不是用系统自带的 apt 版本。系统自带的往往版本太老跑新工具会出各种奇怪问题。命令大概是这样curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完同样用node -v验证。如果你之前装过旧版本建议先彻底卸载再装避免多版本冲突。那个 “node.js v24.21.0 is not yet released” 的报错原因通常是你复制了某个教程里的命令但那个版本号是写教程的人随手编的或者已经过期的。解决办法很简单去 Node.js 官网看当前 LTS 版本号是多少用真实存在的版本。别迷信教程里的具体版本号认准 LTS 这个原则就行。注意如果你在 Windows 上遇到权限问题比如 npm 全局安装时报 EACCES 错误不要用管理员权限硬跑。正确做法是配置 npm 的全局目录到一个你有写权限的路径或者用 nvm-windows 这类版本管理工具来管理 Node.js。3.2 YAML 配置文件位置、结构与缩进陷阱YAML 文件在 openrig 体系里通常放在项目根目录或者用户配置目录下具体位置取决于工具约定。Claude Code 和 Codex 各有自己的配置查找路径openrig 一般会统一到一个地方比如~/.openrig/config.yaml或者项目根目录的.openrig.yaml。一个典型的 openrig 配置大概长这样endpoints: local-qwen: base_url: http://127.0.0.1:1234/v1 api_key: not-needed model: qwen2.5-coder remote-glm: base_url: https://api.example.com/v1 api_key: your-key-here model: glm-4 tools: claude-code: default_endpoint: local-qwen extra_args: - --dangerously-skip-permissions codex: default_endpoint: remote-glm extra_args: []这个结构里endpoints定义模型服务地址tools定义每个工具用哪个端点、带什么参数。你换模型的时候只改default_endpoint指向的名字就行。YAML 最大的坑是缩进。它不用花括号靠空格层级来表达结构。上面例子里base_url前面是两个空格endpoints下面第一层也是两个空格这个层级关系必须严格一致。用 Tab 键缩进是绝对不行的YAML 规范不允许 Tab很多解析器会直接报错。我建议在编辑器里把 Tab 自动转成两个空格VS Code 里搜 “insert spaces” 就能设置。另一个常见问题是冒号后面的空格。base_url: ...冒号后面必须有一个空格写成base_url:...有些解析器能容忍有些直接报错。字符串值建议统一用引号包起来尤其是包含特殊字符或者以数字开头的时候不加引号容易被解析成数字或布尔值。3.3 Claude Code 与 Codex 的安装与验证Node.js 就绪之后装 Claude Code 和 Codex 就是一条 npm 命令的事。Claude Code 的安装命令类似npm install -g anthropic-ai/claude-codeCodex 的安装命令根据官方文档来通常是npm install -g加上对应的包名。装完之后用claude --version和codex --version验证。这里有个细节全局安装-g需要 npm 有全局目录的写权限。如果你在 Ubuntu 上直接用 sudo 装可能会把文件装到 root 目录下后续普通用户跑的时候找不到。更稳的做法是配置 npm 的 prefix 到用户目录npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把这两行加到你的.bashrc或.zshrc里以后全局安装的包都在用户目录下不需要 sudo也不会污染系统目录。装完之后先别急着接模型用官方默认配置跑一次确认工具本身能正常工作。Claude Code 首次运行会引导你登录或者配置 API keyCodex 类似。这一步跑通了再去接 openrig 的配置出问题的时候才能分清是工具本身的问题还是配置的问题。4. 模型接入实战从本地模型到第三方 API4.1 接入 LM Studio 本地模型的完整流程本地模型的好处是不用联网、不消耗额度、数据不出本机。LM Studio 是目前比较流行的本地模型运行工具它自带一个兼容 OpenAI 接口的服务器。让 Claude Code 或 Codex 通过 openrig 接上 LM Studio流程大概是这样的。第一步在 LM Studio 里加载一个模型比如 Qwen2.5-Coder 或者 DeepSeek-Coder然后在 “Local Server” 标签页启动服务。默认地址通常是http://127.0.0.1:1234接口路径是/v1。启动后你可以用 curl 测一下curl http://127.0.0.1:1234/v1/models能返回模型列表就说明服务正常。第二步在 openrig 的 YAML 配置里加一个端点base_url 填http://127.0.0.1:1234/v1api_key 随便填一个非空字符串LM Studio 不校验model 填你在 LM Studio 里加载的模型标识。第三步把你要用的工具Claude Code 或 Codex的 default_endpoint 指向这个端点然后启动工具测试。这里有个关键点不是所有本地模型都能很好地支持工具调用function calling和长上下文。Claude Code 和 Codex 这类工具对模型的指令遵循能力要求比较高如果本地模型太小或者没针对代码场景微调过体验会很差。我实测下来7B 以下的模型基本没法用13B 以上、专门做过代码微调的模型才勉强能跑32B 或者更大的效果才比较接近可用状态。提示本地模型跑起来对显存要求很高。量化版本比如 Q4_K_M能大幅降低显存占用但会损失一些质量。如果你的显卡显存有限优先选量化版本同时把上下文长度调小一点避免爆显存。4.2 接入第三方兼容 API 的配置要点第三方 API 的情况比本地模型复杂因为不同服务商的接口兼容程度不一样。有些完全兼容 OpenAI 的/v1/chat/completions有些只兼容一部分有些连认证方式都不一样。openrig 的适配层要处理的就是这些差异。配置的时候重点看三个东西base_url、认证方式、模型名称格式。base_url 要填到版本号那一层比如https://api.example.com/v1不要填到具体的端点路径。认证方式通常是 Bearer Token放在请求头里openrig 会帮你处理。模型名称要严格按照服务商文档里写的填大小写和连字符都不能错。热词里那个 “the gpt-5.6-sol model is not supported when using codex with a” 报错就是模型名称或者模型类型不匹配导致的。Codex 对模型有特定的要求不是什么模型都能接。遇到这种报错先确认你填的模型名称在服务商的模型列表里真实存在再确认这个模型是否支持 Codex 需要的接口格式。还有一个常见问题是 “your organization has disabled claude subscription access for claude code”。这个报错跟 openrig 关系不大是 Claude Code 本身的订阅权限问题。如果你用的是组织账号可能管理员关闭了 Claude Code 的访问权限。解决办法是换个人账号或者联系管理员开通。这种问题在配置层面解决不了得从账号权限入手。4.3 多工具共用一套端点的路由策略openrig 比较有意思的一个能力是让多个工具共用端点但根据工具类型走不同的路由。比如你想让 Claude Code 用本地模型做日常补全让 Codex 用远程 API 做复杂重构就可以在配置里分别指定。更进一步你还可以做条件路由。比如根据项目类型、根据时间段、根据任务复杂度来切换端点。这些高级用法需要 openrig 支持相应的路由规则配置具体写法要看项目文档。核心思路是一样的把“用哪个模型”这个决策从工具里抽出来放到 openrig 这一层统一管理。这样做的好处是灵活。今天本地模型效果好就用本地明天远程 API 降价了就切远程改一个配置项的事不用动工具本身的任何设置。对于需要频繁切换模型的场景这种设计能省下大量重复配置的时间。5. 常见问题排查与避坑经验5.1 安装与版本类问题速查报错关键词大概率原因处理方式node.js vXX is not yet released版本号不存在或写错去官网确认当前 LTS 版本号error installingnpm 权限不足或网络问题配置用户级 prefix检查网络command not found全局 bin 目录不在 PATH把 npm 全局 bin 加入 PATHEACCES全局安装权限不足不要用 sudo改 prefix版本冲突多版本 Node.js 共存用 nvm 统一管理这张表里的问题我基本都遇到过。最烦的是 PATH 问题装完了命令找不到查半天才发现是环境变量没配。Ubuntu 上尤其容易出这个问题因为不同安装方式把 bin 目录放在不同位置。我的建议是装完之后立刻which claude和which codex确认一下路径不对就手动加 PATH。5.2 配置解析与端点连接类问题YAML 解析失败是最常见的配置问题。报错信息通常会说 “did not find expected key” 或者 “mapping values are not allowed here”翻译过来就是缩进错了或者冒号后面少了空格。排查方法是用在线 YAML 校验工具把你的配置贴进去它会告诉你具体哪一行有问题。端点连接失败分几种情况。如果是 connection refused说明目标服务没启动或者地址端口不对。如果是 401 或 403说明认证信息有问题。如果是 404说明路径不对很可能是 base_url 多写了或者少写了/v1。如果是 500说明目标服务内部出错了得去看服务端的日志。热词里那个 “cc switch local proxy failed while handling codex endpoint /responses” 属于适配层的路径处理问题。Codex 用的端点路径和 Claude Code 不一样openrig 在转发请求的时候如果路径拼接逻辑有 bug就会出这个错。遇到这种情况先确认 openrig 版本是不是最新的然后看它的 issue 列表里有没有类似问题。如果是自己改的适配代码重点检查路径拼接那一段。5.3 模型行为异常与性能问题模型接上了不代表就能好好干活。常见的行为异常包括不遵循指令、乱改无关代码、上下文丢失、响应特别慢。这些问题往往不是 openrig 的锅而是模型本身或者参数配置的问题。不遵循指令通常是模型能力不够换个更强的模型能解决。乱改无关代码可能是上下文给太多了模型分不清重点可以试试缩小上下文范围。上下文丢失检查一下上下文长度设置有些工具默认的上下文窗口比较小长文件处理到一半就忘了前面说了什么。响应慢如果是本地模型看显存是不是爆了或者模型是不是太大跑不动如果是远程 API看网络延迟和服务商限流。我个人的经验是AI 编程工具的效果模型能力占七成配置和用法占三成。别指望一个 7B 的本地模型能做出和顶级远程模型一样的效果那不现实。选模型的时候先明确自己的需求是追求效果还是追求隐私和成本然后在这个约束下选最好的。6. 把 openrig 用顺手的几个进阶思路6.1 配置版本化管理openrig 的配置文件建议纳入 Git 管理但 API key 这类敏感信息不要直接提交。做法是配置文件里用环境变量占位比如api_key: ${GLM_API_KEY}然后在一个不提交的.env文件里填真实值。这样配置可以版本化、可以分享、可以回滚敏感信息也不会泄露。多台机器同步配置的时候这个做法尤其有用。你在公司电脑和家里电脑上用同一份配置只需要各自维护自己的.env文件就行。6.2 按项目切换配置不同项目可能需要不同的模型和参数。比如前端项目用某个模型后端项目用另一个。openrig 如果支持项目级配置覆盖就可以在项目根目录放一个.openrig.yaml它会覆盖全局配置里的对应项。这样你进入不同项目目录工具自动用对应的模型不用手动切换。如果不支持项目级覆盖也可以写个简单的 shell 函数根据当前目录切换配置文件软链接。原理是一样的都是让配置跟着项目走。6.3 日志与调试出问题的时候日志是第一手资料。openrig 和它托管的工具一般都会输出日志关键是知道去哪看。Claude Code 和 Codex 通常会在用户目录下建一个日志文件夹openrig 自己的日志位置看文档。调试的时候把日志级别调高能看到详细的请求和响应内容对定位问题帮助很大。我习惯在接入新端点的时候先开调试日志跑一次确认请求发出去了、响应回来了、格式对得上然后再关掉日志正常用。这样能避免很多“看起来能用但偶尔出问题”的情况。6.4 安全与权限的边界AI 编程工具能执行终端命令这件事方便是真方便危险也是真危险。Claude Code 有个--dangerously-skip-permissions参数跳过所有权限确认用起来爽但风险高。我的建议是日常开发不要开这个参数让它每次执行命令前问你一下。只有在完全可控的环境里比如一次性容器或者虚拟机里才考虑跳过权限确认。openrig 作为中间层理论上可以加一层权限控制比如限制哪些命令能执行、哪些目录能访问。如果你的 openrig 版本支持这类功能建议配置上。安全这东西平时感觉不到价值出事的时候才知道重要。6.5 后续扩展方向openrig 这类项目的想象空间挺大。往小了说可以做成一个统一的 AI 编程工具管理器装工具、配模型、切端点全在一个界面里完成。往大了说可以做成一个 AI 编程工作流编排层根据任务类型自动选择合适的工具和模型甚至让多个工具协作完成一个复杂任务。我个人的体会是现在这个阶段工具本身还在快速迭代过早追求大而全的编排可能不划算。先把基础的多工具配置管理做扎实让日常使用顺畅这个价值就已经很大了。等工具生态稳定一些再往上做编排层成功率会高很多。最后分享一个小技巧如果你同时用 Claude Code 和 Codex给它们配不同的主题色或者提示符前缀这样在终端里一眼就能看出当前是哪个工具在跑避免搞混。这个细节很小但实际用起来能省不少心。