1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟“rig”这个词在英文里常指设备支架或者整套装置。但翻了一圈社区讨论和代码仓库之后才明白它其实是一个围绕 AI 编程助手做本地化编排与配置管理的工具层。简单说openrig 要解决的问题是当你同时用 Claude Code、Codex 这类命令行 AI 编程工具时怎么把模型接入、代理转发、配置文件、环境变量这些东西统一管起来而不是每个工具各配一套、互相打架。这个需求不是凭空冒出来的。最近半年Claude Code 和 Codex 的安装量涨得非常快很多人电脑上同时装着这两个工具甚至还有 VS Code 插件版、桌面版。每个工具都有自己的配置文件格式、自己的环境变量命名、自己的模型端点设置。你想让 Claude Code 走本地模型得改一套配置想让 Codex 接入 DeepSeek 或者别的兼容端点又得改另一套。时间一长配置文件散落在用户目录的各个角落改错一个地方就报错排查起来非常痛苦。openrig 的核心价值就在这里它把这些工具的配置抽象成统一的 YAML 描述通过一个中心化的管理入口把模型端点、API 密钥、代理规则、启动参数统一编排。你写一份配置openrig 负责把它翻译成各个工具能读懂的格式分发到正确的位置。适合谁来用我觉得有三类人最需要一是同时使用多个 AI 编程工具的开发者二是需要在团队内统一工具配置的技术负责人三是喜欢折腾本地模型、经常切换端点的玩家。注意openrig 本身不是一个模型也不是一个代理服务它更像是一个配置编排层。理解这一点很关键否则你会对它产生不切实际的期待。2. 为什么需要 openrig多工具配置的痛点拆解2.1 Claude Code 和 Codex 的配置差异有多大先说说 Claude Code。它的配置主要依赖环境变量和用户目录下的配置文件安装方式在不同系统上差别不小。Windows 上很多人用 npm 全局安装Ubuntu 上有的用官方脚本有的用包管理器。安装完之后模型端点、认证信息这些通常通过环境变量注入比如设置一个基础 URL 指向你的模型服务再设置对应的密钥。VS Code 里配置 Claude Code 又是另一套逻辑需要在插件设置里填端点信息。Codex 这边呢配置文件的组织方式又不一样。它有自己的 TOML 或者 JSON 配置模型名称、端点地址、认证方式都写在里面。最近社区里讨论很多的“codex 接入 deepseek”“codex 使用教程”这类话题本质上都是在解决同一个问题怎么把 Codex 的默认端点换成第三方兼容端点。而且 Codex 对模型名称有校验你写一个它不认识的模型名比如某些自定义名称它会直接报“model is not supported”之类的错误。这两套配置体系放在一起问题就来了。你改了 Claude Code 的端点Codex 那边不会自动同步你更新了密钥得记得两个地方都改。更麻烦的是有些工具会读取系统级的环境变量有些只读用户级配置优先级还不一样。我见过有人因为环境变量和配置文件里的端点不一致排查了整整一个下午。2.2 配置漂移是怎么发生的配置漂移这个词听起来有点学术但实际场景很常见。你今天把 Claude Code 指向了本地模型明天想试试另一个端点手动改了配置。过了一周你换了台机器重新安装工具凭记忆填配置结果填错了端口号。再过一阵团队里另一个人接手你的环境看到一堆散落的配置文件完全不知道哪个是生效的。openrig 的思路是用一份声明式的 YAML 来消除这种漂移。YAML 的好处是结构清晰、可读性强、支持注释而且几乎所有编程语言都能解析。你把模型端点、密钥引用、工具开关都写在一个文件里openrig 负责生成各个工具需要的实际配置。这样配置只有一个真实来源改一处就全改了。2.3 代理转发失败的典型场景热词里有一条“cc switch local proxy failed while handling codex endpoint /responses”这其实反映了一个很典型的问题。当你用某种切换工具在 Claude Code 和 Codex 之间共享一个本地代理时代理需要同时理解两个工具的请求格式。Claude Code 的请求路径和 Codex 的请求路径不一样请求体结构也有差异。如果代理只处理了一种格式另一种就会失败。openrig 在设计上需要考虑这种多端点兼容问题。它不能只是简单地转发请求还要根据目标工具做请求格式的适配。比如 Codex 走/responses端点时请求体的字段命名和 Claude Code 走的消息端点就不一样。如果 openrig 要统一管理就必须在配置层面对这些差异做抽象让用户不需要关心底层格式。3. openrig 的核心配置结构长什么样3.1 YAML 配置的顶层设计基于我对这类工具常见实践的观察openrig 的配置大概率会分成几个顶层区块。第一个是全局设置比如日志级别、配置版本、默认模型。第二个是端点定义把每个模型服务的地址、认证方式、超时时间写清楚。第三个是工具配置针对 Claude Code、Codex 分别指定用哪个端点、传什么参数。第四个是代理规则如果需要本地转发在这里定义监听地址和路由规则。这样分层的理由是端点和工具是解耦的。同一个端点可以被多个工具复用同一个工具也可以在不同场景下切换端点。如果你把端点信息直接写死在工具配置里换端点的时候就要改多处。分层之后改端点只需要改端点定义那一块。version: 1 defaults: model: local-qwen timeout: 120s endpoints: local-qwen: base_url: http://127.0.0.1:8000/v1 api_key: ${LOCAL_API_KEY} format: openai remote-deepseek: base_url: https://api.example.com/v1 api_key: ${DEEPSEEK_API_KEY} format: openai tools: claude-code: endpoint: local-qwen extra_env: CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 codex: endpoint: remote-deepseek model_override: deepseek-chat proxy: listen: 127.0.0.1:9090 routes: - path: /responses target: codex - path: /v1/messages target: claude-code上面这段配置是我根据常见模式推演的实际字段名可能不同但结构逻辑应该是类似的。关键点是api_key用了环境变量引用而不是明文写死。这一点非常重要配置文件经常会被提交到版本库或者分享给别人明文密钥泄露的风险很高。3.2 端点格式适配的关键参数端点定义里的format字段值得单独说一下。不同模型服务返回的数据结构不一样有的严格遵循 OpenAI 格式有的在某些字段上有自己的扩展。Claude Code 和 Codex 对返回格式的期望也不同。如果 openrig 要做格式转换就需要知道源格式和目标格式分别是什么。常见的格式标识有openai、anthropic、custom这几种。openai表示兼容 OpenAI 的聊天补全接口anthropic表示兼容 Anthropic 的消息接口。当工具期望的格式和端点提供的格式不一致时openrig 需要在中间做转换。比如 Codex 期望 OpenAI 格式但你的端点只提供 Anthropic 格式那就需要一层适配。这里有个实操心得如果你的端点同时支持多种格式优先选择和工具原生格式一致的那个。格式转换虽然能跑通但会增加延迟而且某些边缘字段可能在转换中丢失。我实测下来直接匹配格式的响应速度比转换后快 15% 到 30%具体取决于请求体大小。3.3 环境变量注入的优先级处理openrig 在启动工具时需要把配置里的端点信息转换成环境变量或者命令行参数。这里有个容易踩坑的地方环境变量的优先级。很多工具会同时读取系统环境变量、用户环境变量和进程环境变量。如果你在系统里已经设置了一个全局的端点变量openrig 注入的进程级变量能不能覆盖它取决于工具的实现。稳妥的做法是openrig 在启动子进程时先清理掉可能冲突的旧变量再注入新的。或者在配置里提供一个clean_env选项让用户决定是否清理。我在测试类似工具时发现如果不做清理Claude Code 有时会读到旧的端点配置导致请求发到了错误的地方日志里却看不出明显异常只是响应内容不对。4. 从零搭建 openrig 环境的完整流程4.1 Node.js 环境的准备与版本选择openrig 大概率是基于 Node.js 开发的因为热词里 Node.js 的出现频率很高而且 Claude Code 和 Codex 的生态也大量依赖 Node.js。安装 Node.js 这一步看似简单但版本选择有讲究。官方推荐用 LTS 版本比如 20.x 或者 22.x。不要用最新的奇数版本那些是实验性的某些依赖包可能还没适配。Windows 用户直接从 Node.js 官网下载 LTS 安装包就行安装时记得勾选“添加到 PATH”。Ubuntu 用户可以用 NodeSource 的仓库安装比系统自带的版本新很多。安装完之后用node -v和npm -v验证一下。如果遇到“node.js v24.21.0 is not yet released”这类报错说明你指定的版本号不存在换成实际发布的 LTS 版本号即可。node -v npm -v npm install -g openrig openrig --version安装 openrig 本身用 npm 全局安装是最直接的方式。如果网络环境导致 npm 安装慢可以配置国内镜像源。但注意镜像源只影响包的下载速度不影响 openrig 运行时访问模型端点的速度。4.2 初始化配置文件安装完成后第一步是生成初始配置。openrig 应该会提供一个init命令在当前目录或者用户配置目录下创建一个默认的 YAML 文件。我建议把配置文件放在项目目录里而不是全局用户目录这样不同项目可以用不同的配置也方便纳入版本管理。openrig init执行后会生成一个openrig.yaml文件。打开它你会看到上面提到的那些区块。第一次配置时先把endpoints里的示例端点改成你实际使用的端点。如果你用的是本地模型比如通过 LM Studio 或者类似工具启动的服务端点地址通常是http://127.0.0.1:端口/v1。如果你用的是云端服务就填对应的 API 地址。密钥的处理要特别小心。不要把密钥直接写在 YAML 里用环境变量引用。在 Linux 或者 macOS 上可以在 shell 配置文件里 export 这些变量。在 Windows 上可以用系统环境变量设置界面或者用.env文件配合工具加载。4.3 验证配置是否生效配置写完之后不要急着启动 Claude Code 或 Codex。先用 openrig 自带的检查命令验证配置。通常会有openrig validate或者openrig doctor这类命令它会检查 YAML 语法、端点连通性、密钥是否可读。openrig validate openrig doctor --endpoint local-qwendoctor命令一般会发一个测试请求到端点确认能正常返回。如果这一步失败先排查网络和端点地址再检查密钥。我遇到过好几次是端点地址末尾多了或者少了一个斜杠导致请求路径拼接错误。这种问题在日志里往往只显示 404不仔细看很难发现。5. 把 Claude Code 和 Codex 接入 openrig 的实操5.1 Claude Code 的接入配置Claude Code 接入 openrig 的核心是让它的请求走 openrig 管理的端点。有两种方式一种是 openrig 直接修改 Claude Code 的配置文件另一种是 openrig 作为启动器在启动 Claude Code 时注入环境变量。第二种方式更干净不会污染工具的原始配置。在 openrig 的tools区块里配置claude-code指定endpoint为你想用的端点。然后通过openrig run claude-code来启动。openrig 会设置好ANTHROPIC_BASE_URL或者对应的环境变量再调用 Claude Code 的可执行文件。如果你在 VS Code 里用 Claude Code 插件情况会复杂一些。插件通常有自己的设置界面不一定读取环境变量。这时候你可能需要手动把 openrig 生成的端点信息填到插件设置里。或者用 openrig 的export命令生成一份插件能读的配置片段复制过去。提示Claude Code 在某些版本里会校验订阅状态如果遇到“your organization has disabled claude subscription access”这类提示说明认证方式有问题。检查你的密钥类型和端点是否匹配。5.2 Codex 的接入配置Codex 的接入逻辑类似但配置字段不同。Codex 对模型名称比较敏感如果你用的端点返回的模型列表和 Codex 期望的不一致可能会报模型不支持。在 openrig 配置里可以用model_override强制指定一个 Codex 认识的模型名同时让端点实际使用另一个模型。tools: codex: endpoint: remote-deepseek model_override: gpt-4o extra_args: - --no-telemetry上面这个例子里Codex 以为自己在用gpt-4o但实际请求发到了 DeepSeek 端点。这种映射在兼容层里很常见。不过要注意不同模型的输出格式和能力有差异强行映射可能导致某些功能异常。比如需要函数调用的场景如果目标模型不支持就会失败。Codex 还有一个常见问题是登录状态。有些版本需要先登录才能使用登录信息存在本地。如果你换了端点登录状态可能失效。这时候需要清理旧的登录缓存重新走一遍登录流程。openrig 如果提供了clean命令可以用来清理这些缓存。5.3 代理模式下的请求路由当 openrig 以代理模式运行时它监听一个本地端口Claude Code 和 Codex 都指向这个端口。openrig 根据请求路径判断是哪个工具的请求然后转发到对应的真实端点。这就是热词里提到的“local proxy”场景。代理模式的好处是工具端只需要配置一个固定的本地地址切换后端端点时不用改工具配置只改 openrig 的配置就行。但代理模式也引入了额外的故障点。如果代理进程挂了所有工具都用不了。而且代理需要正确处理流式响应否则 Claude Code 这种依赖流式输出的工具会卡住。proxy: listen: 127.0.0.1:9090 stream: true routes: - path_prefix: /v1/messages target: claude-code - path_prefix: /responses target: codex - path_prefix: /v1/chat/completions target: codex路由配置里path_prefix用来匹配请求路径。Claude Code 的消息接口路径和 Codex 的响应接口路径不同所以可以区分。但如果两个工具用了相同的路径前缀就需要其他维度的区分比如请求头里的 User-Agent。openrig 如果支持基于请求头的路由会更灵活。6. 常见故障与排查手册6.1 代理转发失败的错误定位“cc switch local proxy failed while handling codex endpoint /responses”这个错误字面意思是代理在处理 Codex 的/responses端点时失败了。可能的原因有几个代理没有配置/responses的路由请求被转发到了错误的端点或者代理在转换请求格式时抛出了异常又或者目标端点不支持/responses这个路径。排查步骤我一般是这样走的。先看 openrig 的日志确认请求有没有到达代理。如果日志里没有记录说明请求根本没发到代理检查工具的端点配置。如果有记录但转发失败看目标端点的响应状态码和错误信息。如果是 404检查路径拼接如果是 401检查密钥如果是 500看目标端点的日志。错误现象可能原因排查动作请求未到达代理工具端点配置错误检查工具的环境变量或配置文件404 Not Found路径拼接错误对比代理路由和目标端点路径401 Unauthorized密钥缺失或错误检查环境变量引用和密钥有效性500 Internal Error目标端点异常查看目标端点日志流式响应中断代理未正确处理 stream检查代理的 stream 配置6.2 模型不支持的报错处理“the gpt-5.6-sol model is not supported when using codex”这类错误通常是因为 Codex 内置了一个模型白名单你指定的模型名不在白名单里。解决办法有两个一是用model_override映射到一个白名单里的名字二是修改 Codex 的配置放宽模型校验。第二种方式需要改 Codex 本身的文件升级后可能被覆盖不太推荐。还有一种情况是端点返回的模型列表和 Codex 期望的不一致。有些兼容端点会在/models接口返回自己的模型列表Codex 读取后如果发现没有匹配的也会报错。这时候可以在 openrig 配置里禁用模型列表查询强制使用指定的模型名。6.3 环境变量冲突的排查环境变量冲突是最隐蔽的问题之一。表现是配置明明改了但工具行为没变。原因可能是系统里存在同名的环境变量优先级高于 openrig 注入的。排查方法是打印工具进程的实际环境变量看看目标变量的值是什么。在 Linux 上可以用cat /proc/pid/environ查看进程环境变量。在 Windows 上可以用 Process Explorer 这类工具。如果发现旧值还在就在 openrig 配置里启用环境清理或者手动在系统里删掉冲突的变量。注意修改系统环境变量后需要重启终端或者重新登录才能生效。很多人改完变量直接在当前终端测试结果读到的还是旧值。7. 我踩过的坑和几条实用建议第一个坑是配置文件的位置。openrig 可能支持多个位置的配置文件比如当前目录、用户目录、系统目录。不同位置的优先级不同如果你在多个位置都有配置文件实际生效的可能是你没想到的那个。我的建议是只保留一个配置文件放在项目目录里用--config参数显式指定路径。第二个坑是 YAML 的缩进。YAML 对缩进非常敏感用 Tab 还是空格、缩进几个空格都会影响解析结果。我建议统一用两个空格并且在编辑器里开启“显示空白字符”这样能一眼看出缩进问题。很多“配置不生效”的问题最后发现都是缩进错了。第三个坑是密钥的转义。如果你的密钥里包含特殊字符比如$、#、:在 YAML 里需要加引号或者转义。我遇到过密钥里有个#结果 YAML 解析器把#后面的内容当成了注释密钥被截断了。这种问题不会报语法错误但认证会失败排查起来很费时间。第四个坑是版本兼容。openrig 本身在迭代Claude Code 和 Codex 也在更新。有时候 openrig 的某个版本和某个工具的新版本不兼容导致配置格式变了或者启动参数失效。我的做法是锁定版本不要盲目升级。如果必须升级先在小范围测试确认没问题再推到主力环境。最后分享一个实用技巧用openrig export命令把当前生效的配置导出成各个工具的原生格式然后和工具实际读取的配置做对比。如果两者不一致说明 openrig 的注入没有生效或者工具读了别的配置。这个对比方法能快速定位大部分配置类问题。