1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里最常出现在矿机架、测试台架这类场景。翻了翻社区讨论和几个仓库的 README 之后才反应过来它其实是围绕 Claude Code、Codex 这类命令行 AI 编程工具做的一套配置编排方案核心载体是 YAML 文件运行环境依赖 Node.js。说白了openrig 想解决的是同一个开发者手里同时有好几个 AI 编程助手、每次换工具都要重新配一遍环境、改一遍模型端点、调一遍参数的问题。你可以把它理解成一个接线板。Claude Code 是一路电Codex 是另一路电本地跑的模型服务又是第三路openrig 做的事情就是把这些线路统一接到一块板子上用一份 YAML 描述清楚谁接谁、走哪个端点、用哪个模型、超时多少秒。以后要换模型或者换工具改 YAML 就行不用去翻每个工具各自的配置文件。这个项目适合谁我梳理了三类人。第一类是已经在用 Claude Code 或者 Codex但被多套配置搞得头大的开发者第二类是刚接触命令行 AI 工具想一次性把环境搭利索、不想反复踩坑的新手第三类是想把本地模型和云端模型混着用、需要一套统一编排层的中高级用户。如果你只是偶尔用网页版问两个问题那 openrig 对你来说属于杀鸡用牛刀可以先跳过。需要提前说明的是openrig 目前并不是一个官方大厂背书的产品更多是社区驱动的编排思路和配置约定。所以下面讲的内容一部分来自公开资料一部分是我自己在搭类似环境时总结的通用做法涉及具体参数的地方我会标注清楚哪些是约定俗成的、哪些需要你按自己环境调整。2. 整体设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选 YAML 作为配置载体这个决定我认为是对的但理由不是YAML 更高级。真实原因是这类 AI 工具编排配置里嵌套层级深、注释需求多、还经常要写多行字符串比如系统提示词、端点路径模板JSON 不支持注释、多行字符串写起来要转义TOML 表达深层嵌套又很别扭。YAML 在这三点上都能打代价是对缩进极其敏感一个空格错位整个文件就废了。我踩过的坑用 Tab 缩进 YAML。这是新手第一大死因YAML 规范明确禁止 Tab 作为缩进符但很多编辑器默认 Tab 就是 Tab。解决办法是在 VS Code 里把editor.insertSpaces设为 true、editor.tabSize设为 2并且打开renderWhitespace让空格可视化。这一步做完后面能省掉一半的排查时间。2.2 为什么依赖 Node.js 生态Claude Code 和 Codex 的命令行版本都是 Node.js 写的通过 npm 全局安装。openrig 作为编排层自然跟着这套生态走。这意味着你的机器上必须有一个可用的 Node.js 运行时而且版本不能太老。社区里反馈比较多的一个报错是error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个错误的本质是你指定的版本号在镜像源里根本不存在不是网络问题是版本号写错了或者镜像同步滞后。选 Node.js 还有一个隐性好处npm 的全局 bin 目录天然适合放这类 CLI 工具npm install -g之后命令直接进 PATH不用手动配环境变量。坏处是全局包多了之后版本冲突会很难查所以我现在习惯用 nvm 或者 fnm 这类版本管理器把不同项目锁在不同 Node 版本上。2.3 编排层的核心抽象端点、模型、工具三件套openrig 的配置逻辑我拆下来看就是三个核心概念在互相组合。端点endpoint指的是请求最终发到哪里可能是一个云端 API 地址也可能是本地起的服务端口模型model指的是这次请求要用哪个模型标识比如某个具体的模型名工具tool指的是 Claude Code、Codex 这些消费端它们各自有自己的调用格式和参数习惯。编排的价值就在于把这三者解耦。以前你换一个模型得去 Claude Code 的配置里改一遍、去 Codex 的配置里再改一遍两边格式还不一样。现在你在 openrig 的 YAML 里改一处映射关系两个工具读同一份配置行为就同步了。这个思路和前端工程里的环境变量注入、后端里的配置中心是一个道理只是换了个场景。3. 核心细节解析与实操要点3.1 环境准备Node.js 装对版本比装最新版重要装 Node.js 这件事新手最容易犯的错是无脑下最新版。我建议你先确认两件事一是 Claude Code 或 Codex 官方文档里写的推荐 Node 版本区间二是你系统里已有的 Node 版本。查看命令很简单node -v npm -v如果提示 command not found说明没装或者没进 PATH。Windows 用户去官网下载 LTS 版本的安装包一路下一步即可安装程序会自动配好 PATH。macOS 用户我更推荐用版本管理器# 以 fnm 为例先装 fnm brew install fnm # 在 shell 配置里初始化zsh 用户加到 ~/.zshrc eval $(fnm env --use-on-cd) # 装一个 LTS 版本 fnm install --lts fnm use --ltsLinux 用户可以用 nvm逻辑类似。为什么强调版本管理器因为 AI 工具迭代快今天要 Node 18明天可能要 Node 20用管理器切换只要一条命令不用卸载重装。注意如果你在 Windows 上遇到node.js v24.21.0 is not yet released这类报错先别怀疑网络去官网确认这个版本号是否真实存在。很多教程里的版本号是过时的或者笔误的。3.2 YAML 配置文件的骨架长什么样openrig 的 YAML 没有唯一标准格式但社区里常见的骨架大致是这样几块全局设置、端点定义、模型映射、工具绑定。我按这个思路给一份可参考的模板字段名你可以按自己实际用的版本调整# openrig 配置示例字段名以实际版本为准 version: 1 global: timeout: 60 # 单次请求超时秒数 retry: 2 # 失败重试次数 log_level: info endpoints: local_llm: base_url: http://127.0.0.1:1234/v1 api_key: not-needed cloud_a: base_url: https://api.example.com/v1 api_key: ${CLOUD_A_KEY} # 从环境变量读取别硬编码 models: fast: endpoint: local_llm name: qwen2.5-7b-instruct strong: endpoint: cloud_a name: some-large-model tools: claude_code: default_model: strong env: ANTHROPIC_BASE_URL: ${endpoints.cloud_a.base_url} codex: default_model: fast env: OPENAI_BASE_URL: ${endpoints.local_llm.base_url}这份配置里最关键的设计是api_key 用环境变量引用而不是明文写死。我见过太多人把 key 直接贴进 YAML 然后传到公开仓库第二天就收到额度被刷爆的通知。${VAR_NAME}这种写法在大多数配置加载器里都支持加载时从环境变量取值。3.3 端点配置的三个易错点端点这块我总结了三个高频翻车点。第一是base_url 结尾的斜杠。有的工具要求http://host:port/v1有的要求http://host:port/v1/差一个斜杠就可能 404。我的做法是先在浏览器或者 curl 里手动打一次确认哪个能通再写进配置curl -s http://127.0.0.1:1234/v1/models第二是本地服务的监听地址。本地模型服务如果只监听127.0.0.1那只有本机能访问如果你在容器里跑工具、服务在宿主机上就得让服务监听0.0.0.0然后工具里填宿主机的实际地址。第三是端口冲突。本地模型服务常用的端口就那几个很容易和你已有的服务撞车起服务前先lsof -i :端口号看一眼。3.4 模型映射别名机制是编排的灵魂模型映射这一层我强烈建议用别名而不是直接写模型全名。原因很实际模型更新换代太快今天叫xxx-v2下个月可能就xxx-v3了。如果你在 Claude Code 和 Codex 的配置里到处写全名换模型时就是一场灾难。用别名之后你只需要在 models 段里改一处映射所有引用这个别名的地方自动跟着变。别名怎么起我习惯按用途而不是按模型名起比如fast快但能力一般适合补全、格式化、strong慢但强适合复杂重构、架构设计、cheap便宜适合批量任务。这样即使底层模型换了你的心智模型不用变。4. 实操过程与核心环节实现4.1 从零到跑通的第一条链路我按最简路径走一遍目标是让 Claude Code 通过 openrig 配置连上一个本地模型服务。第一步确认本地模型服务已经起来并且能响应curl -s http://127.0.0.1:1234/v1/models | head -c 500能返回模型列表就说明服务正常。第二步把 openrig 的 YAML 放到约定位置通常是项目根目录或者用户配置目录具体路径看你的版本说明。第三步安装 Claude Codenpm install -g anthropic-ai/claude-code第四步通过环境变量把端点指过去。这里有个细节Claude Code 读的是它自己的环境变量名openrig 的作用是帮你把这些变量算好、注入进去。如果你不用 openrig手动注入大概是这样export ANTHROPIC_BASE_URLhttp://127.0.0.1:1234 export ANTHROPIC_API_KEYnot-needed claude用 openrig 之后这一步变成读 YAML 自动完成。第五步进 Claude Code 里发一句简单的话测试比如让它解释一段代码。如果卡住不动八成是端点不通或者模型名不对回到 curl 那一步重新验证。4.2 Codex 侧的接入差异Codex 和 Claude Code 虽然都是命令行 AI 工具但它们的配置习惯不一样。Codex 更偏向 OpenAI 风格的接口约定环境变量名、请求路径都可能不同。社区里有个高频报错值得单独拎出来说cc switch local proxy failed while handling codex endpoint /responses。这个错误的字面意思是本地代理在处理 Codex 的/responses端点时失败了根因通常是代理层不认识 Codex 发的请求格式或者端点路径没配对。我的排查顺序是这样的先确认 Codex 实际请求的路径是什么开 verbose 日志看再确认你的端点服务是否支持这个路径最后确认请求体格式是否兼容。很多时候问题出在你以为 Codex 发的是 A 格式实际它发的是 B 格式。另一个常见报错是the gpt-5.6-sol model is not supported when using codex with a...这类错误说明模型名不被当前 Codex 版本识别要么换模型名要么升级 Codex。4.3 多工具共存的目录结构建议当你同时用 Claude Code、Codex 还有别的工具时目录结构不规划好会非常乱。我现在的做法是~/ai-rig/ ├── openrig.yaml # 主配置 ├── env/ │ ├── local.env # 本地模型相关变量 │ └── cloud.env # 云端 key不进版本控制 ├── logs/ │ ├── claude-code.log │ └── codex.log └── scripts/ ├── start-local.sh # 起本地模型服务 └── switch.sh # 切换配置档关键点是env 目录里的密钥文件加进 .gitignorelogs 目录定期清理scripts 里的启动脚本带幂等检查已经在跑就不重复起。这套结构用了大半年切换工具和排查问题都清爽很多。4.4 参数计算超时和重试怎么定超时和重试这两个参数很多人随手填结果要么频繁超时要么卡死不动。我给一个估算方法。本地小模型7B 级别生成 500 token 大概需要 5 到 15 秒取决于你的硬件云端大模型首 token 延迟可能 1 到 3 秒但整体生成速度看服务端负载。所以超时设置要覆盖最坏情况下的完整生成时间我一般设 60 秒起步复杂任务设 120 秒。重试次数不是越多越好。对于幂等的读操作比如让模型解释代码重试 2 次合理对于有副作用的操作比如让模型直接改文件重试可能导致重复修改我一般设 0 或 1并且要求工具本身有确认机制。这个区别很多人不注意踩过坑才知道疼。5. 常见问题与排查技巧实录5.1 高频报错速查表报错关键词大概率原因排查动作node.js vXX is not yet released版本号不存在或镜像滞后去官网核对版本号换 LTScommand not found: claude全局包没装或 PATH 没配npm ls -g看是否装上检查 PATHlocal proxy failed /responses端点路径或请求格式不匹配开 verbose 日志curl 手动验证model is not supported模型名不被识别换模型名或升级工具版本organization has disabled access账号权限或订阅问题检查账号状态换可用凭证YAML parse error缩进用了 Tab 或冒号后没空格开空格可视化逐行核对这张表是我自己攒的遇到新问题会往里加。建议你也维护一份自己的因为每个人的环境组合不一样别人的坑不一定是你的坑。5.2 排查的通用心法从外往里剥我排查这类问题的顺序永远是网络层 → 服务层 → 配置层 → 应用层。先用 curl 确认端点通不通网络层再确认服务返回的内容对不对服务层然后核对 YAML 里的字段有没有写错配置层最后才怀疑工具本身的 bug应用层。这个顺序能保证你每次都在缩小范围而不是东一榔头西一棒子。举个真实例子。有次 Claude Code 一直转圈不出结果我先 curl 端点通的再看服务日志请求进来了但没返回再一看是模型加载失败显存不够。整个过程五分钟定位如果一上来就怀疑 Claude Code 配置可能折腾半小时还在原地。5.3 几个反直觉的经验第一个反直觉点日志级别不是越高越好。debug 级别日志量巨大反而会拖慢工具响应排查时临时开、查完就关。第二个本地模型不一定比云端快。小模型在弱硬件上跑首 token 延迟可能比云端还高别想当然。第三个配置文件里的注释要写为什么而不是是什么。timeout: 60这种一眼就懂但为什么要 60 而不是 30这个信息三个月后的你自己最需要。提示每次改完配置先跑一个最小验证用例比如让模型回一句ok确认链路通了再干正事。这个习惯帮我省了无数次改了半天发现是配置没生效的时间。6. 进阶玩法与扩展方向6.1 用配置档切换不同工作场景openrig 的 YAML 支持多份配置之后你可以按场景切档。比如写代码档用强模型、写文档档用快模型、离线档全走本地。切换脚本可以很简单#!/bin/bash # switch.sh cp ~/ai-rig/profiles/$1.yaml ~/ai-rig/openrig.yaml echo switched to profile: $1配合 shell 别名rig work、rig doc、rig offline一条命令切换。这个玩法用熟了之后你会发现自己不再纠结到底用哪个模型而是让场景决定。6.2 把本地模型和云端模型串起来一个更进阶的思路是分层路由简单请求走本地复杂请求走云端。实现方式是在编排层加一个判断逻辑比如按 prompt 长度、按任务类型、按关键词路由。这个逻辑可以写在包装脚本里也可以借助支持路由的中间层服务。我试过一个简化版prompt 短于 200 字符走本地否则走云端实测下来能省不少云端额度代价是偶尔本地模型答不好简单问题需要手动重试。6.3 配置的版本管理与团队共享如果你在团队里推这套东西配置一定要进版本控制但密钥绝对不能进。我的做法是仓库里放openrig.example.yaml真实配置由每个人本地生成密钥从各自的密码管理器或者环境变量注入。新人入职时clone 仓库、复制示例配置、填自己的 key三步搞定。这个流程比把配置发群里靠谱一百倍也避免了密钥泄露的经典事故。我在实际使用中最大的体会是openrig 这类编排工具的价值不在于它本身多复杂而在于它逼你把端点、模型、工具这三件事想清楚。想清楚之后哪怕你哪天不用 openrig 了这套心智模型照样能迁移到别的工具上。最后分享一个小技巧每次遇到新报错别急着搜先把完整报错信息复制下来去掉里面的路径和密钥再拿去搜命中率会高很多也避免把自己的敏感信息暴露出去。