1. 从“openrig”说起一个被低估的本地AI编码环境编排思路第一次看到“openrig”这个词我脑子里蹦出来的不是某个具体软件而是一种做法把散落在各处的AI编码工具、模型接口、项目配置和运行环境用一套轻量的结构“架”起来让它们像一台调试台一样协同工作。rig这个词本身就有“装配、架设”的意思open则点明了它的开放属性——不绑定某一家模型不锁死某一种客户端而是围绕你自己的机器和项目把Claude Code、Codex这类命令行编码代理以及YAML配置、Node.js运行时这些基础件组合成一个可复用、可迁移的工作台。这套思路解决的核心问题很实际现在用AI写代码的人越来越多但大多数人的状态是“工具装了一堆配置散落一地”。Claude Code装在一个终端里Codex装在另一个目录模型切换靠改环境变量项目级的规则写在某个隐藏文件里换台机器就得从头再来一遍。openrig要做的就是把这些东西收敛成一份可版本管理的配置让“我的AI编码环境”变成一个可以clone、可以分享、可以回滚的工程而不是一堆只存在于某台电脑上的肌肉记忆。它适合谁如果你已经在用或者准备用Claude Code、Codex这类终端里的编码代理如果你受够了每次换模型都要翻文档改配置如果你希望团队里几个人用同一套规则和同一批模型接口那这套东西值得你花一个下午搭起来。哪怕你只是刚装完Node.js、还在研究YAML文件怎么写的新手理解openrig的组织方式也能帮你少走很多弯路——因为它本质上是在回答一个问题当AI工具越来越多我们该怎么管住它们而不是被它们管住。我下面要展开的不是某个官方文档的复述而是我自己在几台机器上反复搭、反复拆之后总结出来的一套可落地的编排方法。核心关键词会自然穿插在各个环节里openrig作为整体思路Claude Code和Codex作为两个主要的编码代理入口YAML作为配置载体Node.js作为运行时底座。你不需要全部照搬但每一块背后的“为什么”值得你看完。2. 整体设计与思路拆解为什么是“编排”而不是“安装”2.1 先想清楚你要的是工具还是工具之间的关系很多人装AI编码工具的顺序是反的先看到某个工具火就去装装完发现模型不对又去改配置改完发现项目里还有另一套规则最后环境乱成一锅粥。openrig的思路是先定义关系再填工具。具体来说它把整个环境拆成四层运行时层Node.js及其包管理器负责让Claude Code、Codex这些基于Node的工具能跑起来。这一层要的是稳定不是最新。代理层Claude Code、Codex这类命令行编码代理它们是真正和你对话、读写文件、执行命令的“手”。模型接入层决定代理背后调用哪个模型是官方接口、本地模型还是第三方兼容接口。这一层最容易被写死也最需要解耦。项目配置层YAML文件承载的项目级规则、模型参数、工具行为让同一套代理在不同项目里表现不同。这四层分开之后你会发现很多之前纠结的问题变得清晰模型换了只动接入层项目规则变了只动配置层换台机器运行时层重装一次上面三层跟着配置走。openrig的价值不在于发明了新工具而在于把这四层的关系用文件和目录固定下来。2.2 为什么选YAML作为配置载体热词里反复出现“yaml文件”“yolov10 yaml文件怎么创建”“rstudio的yaml在哪里”说明YAML对很多人来说还是个需要查的东西。但在openrig这类编排场景里YAML几乎是默认选择原因有三个。第一它对人友好。JSON写多了会疯满屏的引号和括号改一个参数要数半天层级。YAML用缩进表达结构写模型名、路径、开关这些配置时一眼能看出谁属于谁。第二它对机器也友好。Node.js生态里解析YAML的库非常成熟Claude Code和Codex的很多配置本身就支持YAML格式你不需要额外造轮子。第三它适合做版本管理。YAML是纯文本diff起来干净团队里谁改了哪个参数git log里看得清清楚楚。注意YAML对缩进极其敏感Tab和空格混用是新手最常见的翻车点。我的习惯是全程用两个空格并且在编辑器里打开“显示空白字符”从源头上避免。2.3 Node.js版本选择别追新追LTS热词里有一条很典型“error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava”。这就是追新版本踩的坑。Node.js的版本号里偶数版本是LTS长期支持奇数版本是当前版生命周期短。Claude Code、Codex这些工具依赖的底层库往往只对LTS版本做过充分测试。我的做法是去Node.js官网下载页面只认LTS那一栏当前是哪个大版本就装哪个。装完之后用node -v和npm -v确认然后把这个版本号记在openrig的文档里。这样下次换机器直接照着装不会因为版本差异导致某个工具跑不起来。如果你用Ubuntu别用系统自带的apt版本那个往往太旧用NodeSource的源或者nvm来管理nvm的好处是可以在不同项目间切换Node版本对openrig这种多工具环境特别有用。2.4 Claude Code与Codex的定位差异这两个工具经常被放在一起讨论但它们在openrig里的角色可以互补。Claude Code更偏向“对话式编码代理”你给它一个任务它会读项目、改文件、跑命令交互感强。Codex则更偏向“命令行里的编码助手”适合快速生成、补全、解释代码片段。热词里“claude code如何直接执行终端命令”“codex cli”“codex使用教程”这些说明大家最关心的就是它们怎么落地。在openrig的编排里我不建议二选一而是让它们共享同一套项目配置和模型接入层。比如项目根目录放一个YAML里面定义好模型端点、超时时间、忽略目录Claude Code和Codex各自读取自己需要的部分。这样你在两个工具之间切换时行为是一致的不会出现“Claude Code里忽略node_modulesCodex里却去读”这种割裂。3. 核心细节解析与实操要点把配置写成可复用的资产3.1 目录结构先定骨架再填肉openrig的目录结构不需要复杂但一定要固定。我用了半年多、改过好几版的方案是这样的openrig/ ├── configs/ │ ├── base.yaml # 全局基础配置模型端点、超时、日志级别 │ ├── claude.yaml # Claude Code专属覆盖项 │ └── codex.yaml # Codex专属覆盖项 ├── projects/ │ └── my-app/ │ └── project.yaml # 项目级规则忽略目录、语言偏好 ├── scripts/ │ ├── setup-node.sh # Node.js环境检查与安装提示 │ └── switch-model.sh # 模型切换脚本 └── README.md # 记录当前环境状态和版本号这个结构的好处是“分层覆盖”。base.yaml放所有工具共用的东西claude.yaml和codex.yaml只写差异project.yaml再在项目维度上覆盖。读取顺序是base → 工具专属 → 项目后面的覆盖前面的。这样你改一个模型端点只需要动base.yaml一处所有工具和项目跟着变。3.2 YAML配置的写法与常见陷阱一个典型的base.yaml长这样model: provider: openai-compatible endpoint: http://localhost:1234/v1 name: local-coder timeout: 120 max_tokens: 4096 runtime: node_version: 20.x package_manager: npm logging: level: info file: ./logs/openrig.log这里有几个细节值得说。provider写openai-compatible是因为很多本地模型服务和第三方接口都兼容这个协议Claude Code和Codex都能通过配置指向它。endpoint指向本地意味着你的代码不会离开这台机器这对有隐私要求的项目很重要。timeout给到120秒是因为本地模型首次加载或者大上下文时响应会慢给太短会频繁超时。提示YAML里的布尔值不要写成yes或no虽然某些解析器认但标准YAML 1.2里true和false更安全。字符串如果包含冒号记得加引号否则解析会报错。3.3 模型接入层的解耦别把端点写死在工具里热词里“claude code 调用lmstudio的本地模型”“codex接入deepseek”“使用cc switch 接入 deepseek v4, qwen, glm等模型”这些本质上都在做同一件事让编码代理不绑定官方模型。openrig的做法是把模型接入信息全部抽到YAML里工具本身不存任何端点。具体操作上Claude Code和Codex都支持通过环境变量或配置文件指定API地址。我的做法是在启动脚本里读取base.yaml把endpoint和name导出成环境变量再启动工具。这样切换模型时只改YAML不改任何工具内的设置。如果你用cc switch这类切换工具也可以让它读取同一份YAML保持单一数据源。这里有个坑不同模型对参数的支持不一样。比如某些本地模型不支持max_tokens你写了它可能报错。我的经验是在base.yaml里只放最通用的参数模型特有的参数放到项目级YAML里并且加注释说明哪个模型需要哪个参数。这样换模型时至少知道该动哪里。3.4 Node.js环境检查脚本的写法openrig的scripts目录里setup-node.sh不需要真的去装Node.js而是做检查和提示。因为自动安装Node.js在不同系统上差异太大容易出错。脚本的核心逻辑是#!/usr/bin/env bash REQUIRED_NODE20 CURRENT_NODE$(node -v 2/dev/null | sed s/v// | cut -d. -f1) if [ -z $CURRENT_NODE ]; then echo 未检测到Node.js请前往Node.js官网下载LTS版本 exit 1 fi if [ $CURRENT_NODE -lt $REQUIRED_NODE ]; then echo 当前Node.js版本为 $CURRENT_NODE建议升级到 $REQUIRED_NODE LTS exit 1 fi echo Node.js版本检查通过$(node -v)这个脚本看起来简单但它解决了一个真实痛点团队里每个人机器上的Node版本不一样有人用18有人用22导致同一个工具在一个人那里能跑在另一个人那里报错。把版本要求写进脚本新人clone下来第一件事就是跑它问题提前暴露。4. 实操过程与核心环节实现从零搭起一套可用的openrig4.1 第一步确认Node.js与包管理器就绪不管你用Windows、macOS还是Ubuntu第一步都是确认Node.js。去Node.js官网下载LTS版本安装时勾选“添加到PATH”。装完打开终端跑node -v和npm -v。如果两个都有版本号输出说明运行时层就绪。Ubuntu用户注意如果你之前用apt装过Node.js先sudo apt remove nodejs卸掉再去官网下。系统自带的版本往往落后好几个大版本Claude Code和Codex的一些依赖会因此装不上。热词里“ubuntu配置claude code”“ubuntu 安装claude code”出现频率很高说明这个坑踩的人不少。4.2 第二步安装Claude Code与CodexClaude Code的安装官方推荐用npm全局安装。命令是npm install -g anthropic-ai/claude-code装完用claude命令启动。Codex的安装类似具体包名以官方文档为准装完用codex启动。两个都装完后分别在终端里跑一次确认能进入交互界面。这里有个常见问题热词里“your organization has disabled claude subscription access for claude code”和“codex无法加载组织设置”这类报错通常和账号权限或网络环境有关。我的建议是如果你用的是个人账号先确认订阅状态如果是组织账号找管理员确认策略。openrig本身不解决账号问题但它能让你在账号可用时快速把环境配好。4.3 第三步编写base.yaml并验证解析在openrig目录下创建configs/base.yaml内容参考上一节的示例。写完后用Node.js快速验证YAML能不能被正确解析const fs require(fs); const yaml require(js-yaml); try { const config yaml.load(fs.readFileSync(./configs/base.yaml, utf8)); console.log(配置解析成功, config.model.endpoint); } catch (e) { console.error(YAML解析失败, e.message); }跑之前先npm install js-yaml。这个验证步骤很重要因为YAML的缩进错误在工具启动时可能只报一个模糊的错误提前用脚本验证能省很多排查时间。4.4 第四步把模型端点接入Claude CodeClaude Code支持通过环境变量指定API端点。在启动脚本里这样写export ANTHROPIC_BASE_URL$(node -e console.log(require(js-yaml).load(require(fs).readFileSync(./configs/base.yaml,utf8)).model.endpoint)) export ANTHROPIC_MODEL$(node -e console.log(require(js-yaml).load(require(fs).readFileSync(./configs/base.yaml,utf8)).model.name)) claude这段脚本从base.yaml里读出endpoint和model名导出成环境变量再启动Claude Code。这样你改YAML重启脚本模型就换了。实测下来本地模型服务只要兼容OpenAI协议Claude Code基本都能连上。4.5 第五步项目级YAML的覆盖实践在projects/my-app/project.yaml里你可以写项目特有的规则project: name: my-app language: typescript ignore: - node_modules - dist - .git model: max_tokens: 8192然后在启动脚本里先读base.yaml再读project.yaml用后者覆盖前者。这样同一个Claude Code在my-app项目里忽略node_modules在另一个项目里可能忽略别的目录行为跟着项目走。4.6 第六步用脚本一键切换模型switch-model.sh的核心逻辑是接收一个模型名参数修改base.yaml里的model.name和endpoint然后提示重启工具。更优雅的做法是维护一个models.yaml里面列出所有可用模型切换时只改一个引用。这样你可以在本地模型、第三方接口之间快速切换不用每次手改配置。5. 常见问题与排查技巧实录5.1 模型连不上先查端点再查协议热词里“cc switch local proxy failed while handling codex endpoint /responses”这类报错通常出在端点或协议不匹配。排查顺序是先用curl直接请求endpoint确认服务本身活着再确认工具用的协议版本和模型服务支持的是否一致最后看YAML里的endpoint有没有多写或少写路径。我遇到过把/v1写成/v1/导致404的情况这种细节只能靠日志。5.2 YAML解析报错九成是缩进YAML报错信息往往不直观比如“mapping values are not allowed here”实际原因可能只是某一行多了一个空格。我的排查方法是把报错行附近的缩进全部改成两个空格并且确认没有Tab。如果还不行用在线YAML校验工具贴进去它会直接指出哪一行有问题。5.3 Node.js版本冲突用nvm隔离如果你同时维护多个项目有的要Node 18有的要Node 20用nvm最省心。装完nvm后nvm install 20nvm use 20当前终端就切到20。openrig的setup脚本可以检测nvm是否存在存在就提示用nvm切换不存在就提示去官网下载。5.4 工具启动慢检查模型加载和超时本地模型首次启动慢是正常的但如果每次都慢可能是模型太大或者超时设置太短导致反复重试。把base.yaml里的timeout调大并且确认模型服务本身有没有预热机制。有些本地服务支持keep-alive开启后第二次请求会快很多。5.5 常见问题速查表现象可能原因排查动作工具启动报模型不支持YAML里模型名写错或端点不支持该模型用curl测端点确认模型名YAML解析失败缩进混用Tab或冒号未加引号统一两个空格含冒号字符串加引号Node.js版本报错系统Node版本过低或过高用nvm切到LTS版本模型响应超时timeout太短或模型未预热调大timeout检查模型服务日志项目规则不生效project.yaml未被读取或覆盖顺序错在启动脚本里打印最终配置提示每次改完YAML别急着启动工具先用Node.js脚本解析一遍。这个习惯帮我省了至少一半的排查时间。6. 我踩过的坑与几条实在建议openrig这套东西我前后搭了三次第一次把配置写死在工具里换模型时改得想砸键盘第二次把所有配置塞进一个巨大的YAML结果改一个参数要翻半天第三次才拆成base、工具、项目三层才算顺手。如果你刚开始我的建议是别追求一步到位先把base.yaml和Node.js环境弄稳能跑通一个工具再往上加。另外Claude Code和Codex的版本更新很快热词里“claude code官方文档链接”“codex官网下载”这些搜索量高说明大家都在追新。但我的经验是openrig的配置层尽量保持稳定工具版本可以跟着官方走配置格式不要频繁大改。每次工具大版本更新后先在一个项目里试确认YAML还能被正确读取再推广到其他项目。最后分享一个小技巧在README.md里记下当前Node.js版本、Claude Code版本、Codex版本和模型端点每次环境变更就更新一行。看起来不起眼但当你三个月后回到这个项目或者要把环境交给同事时这一页记录能省掉大量“当时是怎么配的”这种回忆成本。openrig的价值最终就体现在这种可追溯、可复现的踏实感上。