1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟“rig”这个词在矿机、直播设备、测试台架这些圈子里太常见了。但把 openrig 和 claude code、codex、yaml、node.js 这几个词摆在一起看方向就清楚了——这是一个围绕 AI 编程助手做配置编排、环境搭建和本地代理转发的工具型项目。说白了它解决的是“我手头有好几个 AI 编程工具怎么让它们统一跑起来、统一配置、统一切换”的问题。我接触 AI 编程助手这条线有一段时间了从最早的命令行补全工具到后来的 claude code、codex 这类能直接读写项目文件、执行终端命令的 agent 型工具踩过的坑不算少。最典型的一个痛点就是每个工具的配置格式不一样认证方式不一样模型接入方式也不一样。claude code 有自己的一套配置逻辑codex 又是另一套你想让它们都指向同一个本地模型或者同一个第三方接口得分别折腾。openrig 的价值就在这里——它试图用一份 yaml 配置把多个 AI 编程工具的运行环境、模型端点、代理规则统一管起来。那它适合谁用我觉得有三类人最需要关注。第一类是同时用 claude code 和 codex 的开发者尤其是需要在不同模型之间来回切换的第二类是想把 AI 编程助手接到本地模型比如通过 LM Studio 跑起来的模型上的人因为本地模型的接口格式和官方接口往往有差异中间需要一层转换第三类是在团队里负责统一开发环境的人一份 yaml 分发下去大家的工具配置就一致了省得每个人各自为战。openrig 这个名字里的“rig”我理解成“装配、搭台子”的意思就是把散落的工具和配置装配成一个能稳定运转的整体。它本身不是模型也不是编程助手而是一层编排和代理的中间件。这个定位很关键理解了这一点后面所有的配置逻辑就都顺了。2. 核心设计思路与方案选型拆解2.1 为什么用 yaml 做统一配置层openrig 选择 yaml 作为配置载体这个决定我认为是非常务实的。你去看 claude code 和 codex 各自的配置有的是 json有的是 toml有的干脆靠环境变量。格式不统一带来的直接后果就是你没法用一套逻辑去管理它们。yaml 的好处在于结构清晰、支持注释、嵌套表达能力强而且 node.js 生态里解析 yaml 的库非常成熟js-yaml 几乎是标配。更重要的是yaml 对人类友好。你写一个多工具的配置里面要区分全局设置、每个工具的独立设置、模型端点、代理规则用 json 写会满屏引号和括号改起来容易出错。yaml 的缩进式结构让层级关系一目了然团队协作时 review 配置也轻松很多。我实测下来一份结构良好的 openrig yaml新人看十分钟就能明白每个字段是干什么的。这里有个细节值得说yaml 对缩进极其敏感tab 和空格混用会直接报错。我见过太多人从网页复制配置片段结果粘贴进去全是 tab解析直接失败。所以 openrig 的配置最好用统一的编辑器设置成“tab 转 2 空格”能省掉大量莫名其妙的报错。2.2 node.js 作为运行时底座的原因openrig 跑在 node.js 上这个选型背后有明确的逻辑。claude code 和 codex 这类工具很多本身就是 node.js 写的或者提供 npm 安装方式运行时环境天然重合。用 node.js 做底座意味着你不需要额外装 python、go 或者 rust 的运行时一个 node 环境就能把整套工具链撑起来。node.js 的另一个优势是它的异步 IO 模型特别适合做代理转发。openrig 要处理的核心场景之一就是请求转发——把 claude code 或 codex 发出的请求转发到本地模型或者第三方接口。这种场景下请求的并发处理、流式响应的透传node.js 的 event loop 机制处理起来很顺手。而且 npm 生态里有大量现成的 http 代理、流处理库不用从零造轮子。不过 node.js 的版本管理是个坑。我强烈建议用 nvm 或者 fnm 来管理 node 版本不要直接装系统级的 node。因为不同工具对 node 版本的要求可能不一样有的要 18 LTS有的要 20 LTS混在一起容易出问题。openrig 本身对 node 版本的要求我建议至少 18 LTS 起步20 LTS 更稳。2.3 代理层设计的核心考量openrig 最核心的技术点我认为是它的代理层设计。为什么需要代理因为 claude code 和 codex 默认都指向官方的接口端点但实际使用中很多人需要把它们指向别的模型服务——可能是本地跑的模型可能是团队内部的网关也可能是第三方兼容接口。这些服务的接口格式和官方接口往往有差异直接改工具的配置又很麻烦所以中间加一层代理做格式转换和路由是最干净的方案。代理层要解决三个问题第一是端点重写把工具发出的请求地址改到目标服务第二是格式适配不同模型的请求体和响应体结构不一样需要转换第三是认证透传把工具带的认证信息正确传递给下游服务。openrig 通过 yaml 配置来定义这些规则你只需要声明“claude code 的请求走哪个端点、用什么格式、带什么认证”剩下的交给它处理。我踩过的一个坑是代理层如果对流式响应处理不当会导致 claude code 那边一直卡着不输出。流式响应的每个 chunk 都要及时透传不能等整个响应结束再一次性返回。openrig 在这块如果用的是 node.js 的 stream pipe基本不会有问题但如果自己手写缓冲逻辑就要特别注意 flush 时机。3. 环境搭建与核心配置实操3.1 node.js 环境准备与版本选择先把地基打好。node.js 的安装我推荐两种方式看你习惯。如果你只是临时用去 node.js 官网下载 LTS 版本的安装包一路下一步就行。但如果你要长期折腾 AI 编程工具这条线强烈建议用版本管理器。在 macOS 或 Linux 上用 nvm 是最省心的curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后重开终端然后nvm install 20 nvm use 20 nvm alias default 20Windows 用户可以用 nvm-windows或者干脆用 fnm速度更快。装好之后验证一下node -v npm -v这里有个常见报错要提前说如果你看到类似“error installing 24.21.0: node.js v24.21.0 is not yet released”这种提示说明你指定的版本号根本不存在或者 nvm 的远程版本列表没更新。解决办法是先nvm ls-remote看看有哪些可用版本别凭记忆瞎写版本号。另外奇数版本号如 21、23是开发版生产环境建议用偶数 LTS 版本。3.2 openrig 的安装与初始化node 环境就绪后openrig 的安装通常走 npm 全局安装的路子npm install -g openrig如果 npm 下载慢可以临时切到国内镜像源npm config set registry https://registry.npmmirror.com装完之后跑一下openrig --version确认安装成功。接下来是初始化配置文件。openrig 一般会在用户目录下找配置文件常见位置是~/.openrig/config.yaml或者当前项目根目录的openrig.yaml。我建议先用全局配置做基础设置项目级的配置做覆盖这样不同项目可以用不同的模型端点。初始化的时候openrig 可能会生成一份模板配置。如果没有自动生成手动创建一个version: 1 tools: claude-code: enabled: true endpoint: http://localhost:1234/v1 codex: enabled: true endpoint: http://localhost:1234/v1 proxy: port: 8787 logLevel: info这份配置的意思是启用 claude code 和 codex 两个工具它们的请求都转发到本地的 1234 端口假设你本地用 LM Studio 跑模型默认端口就是 1234代理服务本身监听 8787 端口。3.3 yaml 配置文件的字段详解配置文件的每个字段都有讲究我逐个拆开讲。version字段是配置格式的版本号openrig 升级后如果配置格式有变化靠这个字段做兼容。别删也别乱改。tools下面是每个工具的独立配置。enabled控制是否启用调试的时候可以单独关掉某个工具。endpoint是这个工具请求要发往的地址。这里要注意endpoint 的路径部分很关键有的服务是/v1有的是/v1/chat/completions写错了会直接 404。proxy段是代理服务本身的设置。port是监听端口别和系统里其他服务冲突8787 是个比较安全的选择。logLevel控制日志详细程度调试阶段设成debug稳定后改回info不然日志刷屏。如果要接入需要认证的服务配置里要加认证信息tools: claude-code: enabled: true endpoint: https://api.example.com/v1 auth: type: bearer token: ${CLAUDE_API_KEY}注意${CLAUDE_API_KEY}这种写法是从环境变量读取不要把密钥明文写在 yaml 里。这是安全底线配置文件很可能被提交到 git明文密钥泄露就是事故。3.4 接入本地模型的完整流程把 claude code 接到本地模型上是 openrig 最实用的场景之一。完整流程是这样的。第一步本地先把模型服务跑起来。以 LM Studio 为例加载一个模型启动本地 server默认监听 1234 端口接口格式是 OpenAI 兼容的。启动后你可以用 curl 验证一下curl http://localhost:1234/v1/models能返回模型列表就说明服务正常。第二步配置 openrig 把 claude code 的请求转发到这个端点。因为 claude code 默认的请求格式和 OpenAI 格式不完全一样openrig 需要做一层转换。配置里通常要指定转换规则tools: claude-code: enabled: true endpoint: http://localhost:1234/v1 adapter: openai-compatible model: local-model-nameadapter字段告诉 openrig 用哪种格式转换器model指定实际调用的模型名。这个模型名要和本地服务里加载的模型标识一致写错了会报“model not found”。第三步启动 openrig 代理openrig start第四步把 claude code 的请求地址指向 openrig 的代理端口。这一步通常通过环境变量或者 claude code 自己的配置完成。具体方式取决于 claude code 的版本有的支持ANTHROPIC_BASE_URL这类环境变量有的要在配置文件里改。我实测下来这套流程跑通后claude code 就能用本地模型做代码补全和对话了。但要注意本地模型的能力和官方模型差距可能很大尤其是长上下文和工具调用能力别期望值太高。4. 多工具协同与代理转发实战4.1 claude code 与 codex 的配置差异处理claude code 和 codex 虽然都是 AI 编程助手但它们的配置逻辑和请求格式差异不小。claude code 的请求体里消息结构、工具调用格式、系统提示词的组织方式和 codex 都不一样。openrig 要同时管这两个就得在代理层做区分。我的做法是在配置里给每个工具单独指定 adaptertools: claude-code: enabled: true endpoint: http://localhost:1234/v1 adapter: anthropic-to-openai codex: enabled: true endpoint: http://localhost:1234/v1 adapter: openai-nativeanthropic-to-openai表示把 anthropic 风格的请求转成 OpenAI 风格openai-native表示 codex 本身就是 OpenAI 风格不用转换。这样两个工具可以共用同一个本地模型端点但各自走各自的转换逻辑。这里有个细节claude code 的工具调用tool use格式和 OpenAI 的 function calling 格式差异很大。如果本地模型不支持工具调用或者转换层处理不好claude code 执行终端命令、读写文件这些功能就会失效。我建议先用简单的对话测试确认基础通路没问题再逐步测试工具调用。4.2 代理转发中的流式响应处理流式响应是代理转发里最容易出问题的地方。claude code 和 codex 都期望服务端以 SSEServer-Sent Events的形式流式返回内容这样用户能看到逐字输出的效果。如果代理层把流式响应缓冲成完整响应再返回用户体验会变得极差而且可能触发超时。openrig 在 node.js 里处理流式响应核心是用 stream 的 pipe 机制。请求进来后代理层把请求转发给下游服务下游返回的响应流直接 pipe 回客户端中间只做必要的格式转换不做缓冲。这样每个 chunk 都能及时透传。如果你自己写代理逻辑要特别注意这几点不要用await response.text()这种一次性读取的方式要用response.body的流式接口转换格式时如果必须缓冲要设置合理的 flush 阈值不能等整个响应结束。我踩过的一个坑是某些本地模型服务的流式响应格式不规范chunk 之间没有正确的分隔符导致代理层解析出错。解决办法是在代理层加一层容错遇到解析不了的 chunk 就原样透传别直接报错中断。4.3 多模型切换的配置策略实际使用中你可能需要在不同模型之间切换——写代码用一个模型写文档用另一个调试用本地小模型。openrig 的配置支持定义多个模型端点然后通过切换配置或者命令行参数来选择。一种做法是在 yaml 里定义模型组models: coding: endpoint: http://localhost:1234/v1 model: deepseek-coder general: endpoint: http://localhost:1234/v1 model: qwen fast: endpoint: http://localhost:8080/v1 model: small-model然后在工具配置里引用tools: claude-code: enabled: true modelRef: coding这样切换模型只需要改modelRef的值不用改一堆端点配置。如果 openrig 支持运行时切换那就更方便了不用重启代理服务。我个人的习惯是日常写代码用 coding 组遇到需要长上下文理解的任务切到 general 组快速问答用 fast 组。这种分层策略能兼顾质量和速度。5. 常见问题排查与避坑经验5.1 配置解析失败的典型原因yaml 配置解析失败是最常见的问题没有之一。我整理了一个排查表报错现象可能原因解决办法解析报错指向某一行缩进用了 tab全部替换成空格字段值为 null冒号后没加空格yaml 要求冒号后必须有空格中文乱码文件编码不是 UTF-8用编辑器转成 UTF-8环境变量没生效变量名拼写错误检查${}里的变量名配置不生效配置文件位置不对确认 openrig 读取的是哪个路径这里重点说缩进问题。yaml 用缩进表示层级同一层级的字段缩进必须完全一致。我见过有人从不同地方复制配置片段有的用 2 空格有的用 4 空格拼在一起就乱了。建议整个配置文件统一用 2 空格缩进编辑器里开启“显示空白字符”一眼就能看出问题。5.2 代理连接失败的排查思路代理连不上排查要按层次来。先确认 openrig 代理服务本身有没有起来curl http://localhost:8787/health如果有健康检查端点能返回就说明代理活着。然后确认下游模型服务是否可达curl http://localhost:1234/v1/models如果这一步失败问题在模型服务不在 openrig。如果模型服务正常但代理转发失败检查配置里的 endpoint 地址是否正确端口有没有写错路径有没有多余或缺失的斜杠。还有一个隐蔽的问题端口冲突。如果 8787 被别的程序占了openrig 启动会失败或者行为异常。用lsof -i :8787看看端口占用情况换个端口就行。5.3 工具端报错的定位方法claude code 或 codex 那边报错信息往往很模糊比如“请求失败”“无法连接”。这时候要看 openrig 的日志。把logLevel设成debug日志里会记录每个请求的完整信息——请求地址、请求头、请求体、响应状态、响应体。对照日志就能定位问题出在哪一环。我遇到过一个典型问题claude code 报“认证失败”但本地模型根本不需要认证。查日志发现claude code 默认会带一个认证头代理层原样转发给了本地服务本地服务不认识这个头就拒绝了。解决办法是在代理配置里加一条规则把不需要的认证头剥掉proxy: stripHeaders: - authorization - x-api-key这种问题不看日志根本想不到所以调试阶段一定要开 debug 日志。5.4 性能与稳定性优化建议跑通之后还要考虑稳定性和性能。几个实操建议。第一给代理层加超时设置。本地模型响应可能很慢如果代理层没有合理的超时请求会一直挂着。但超时也不能太短大模型生成长文本本来就需要时间。我一般设 120 秒起步具体看模型速度。第二注意内存占用。node.js 处理流式响应时如果流没有正确关闭内存会慢慢涨。长时间运行后如果发现内存异常检查是不是有流泄漏。用--max-old-space-size参数限制 node 堆内存配合进程监控能及早发现问题。第三日志轮转。debug 日志写多了会占满磁盘生产环境要用日志轮转工具或者定期清理。openrig 如果支持日志文件大小限制配置上。第四配置版本管理。把 openrig 的 yaml 配置纳入 git 管理每次改动都有记录。团队协作时配置变更走 review 流程避免有人改错了影响所有人。6. 进阶玩法与扩展思路6.1 团队共享配置的落地方案团队里如果多个人用 AI 编程工具配置统一是个大问题。我的做法是建一个内部仓库放一份基准 openrig 配置每个人 clone 下来后用本地覆盖文件做个性化调整。基准配置里定义好团队统一的模型端点、代理规则、日志规范个人覆盖文件里只放自己的认证信息和偏好设置。openrig 如果支持配置继承比如extends字段那就更优雅了# 个人配置 extends: ./team-base.yaml tools: claude-code: auth: token: ${MY_TOKEN}这样团队基准配置更新后个人只需要 pull 一下就能同步不用手动合并。6.2 结合本地模型做离线开发openrig 把 AI 编程工具接到本地模型后最大的好处是离线可用。飞机上、网络差的地方、对数据隐私敏感的场景本地模型都能顶上。虽然本地模型的能力和云端大模型有差距但做代码补全、简单重构、写测试用例这些任务够用了。我实测下来本地跑一个 7B 到 14B 的代码模型配合 claude code 的文件读写能力日常开发效率能提升不少。关键是响应速度快没有网络延迟而且不用担心代码片段被传到外部。配置上要注意本地模型的上下文窗口通常比云端小claude code 如果一次性塞太多文件内容进去会超出窗口。可以在配置里限制单次请求的 token 数或者用 openrig 做请求裁剪。6.3 配置模板与快速复用折腾多了之后我整理了几套配置模板按场景分类本地模型模板、第三方接口模板、混合模式模板。新项目直接复制对应模板改几个字段就能用。模板的价值在于把踩过的坑固化下来。比如本地模型模板里认证头剥离、超时设置、流式响应容错这些都已经配好了不用每次重新踩坑。我建议每个经常用 openrig 的人都维护自己的模板库时间长了就是一笔财富。配置模板还可以参数化用环境变量占位这样一套模板能适配不同的机器和账号。配合 dotenv 之类的工具本地开发用.env文件CI 环境用环境变量注入一套配置到处跑。6.4 后续可扩展的方向openrig 这套思路还能往几个方向扩展。一是支持更多工具除了 claude code 和 codex其他 AI 编程助手如果也有类似的配置需求都可以纳入统一管理。二是增强代理层的可观测性加指标采集统计每个工具的请求量、响应时间、错误率方便优化。三是做配置的图形化管理对不习惯手写 yaml 的人友好一些。不过扩展归扩展核心还是那句话openrig 的价值在于用一层轻量的编排和代理把散落的 AI 编程工具统一管起来。理解了这一点怎么扩展都不会跑偏。我在实际使用中最大的体会是这类工具的价值不在于功能多花哨而在于稳定和省心。配置一次长期受益把折腾环境的时间省下来写代码这才是正经事。