openrig：用YAML和Node.js统一管理Claude Code与Codex的本地AI编程工作流

1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的不是某个具体软件而是一种“开放式装配台”的感觉。rig 在英文里本意是“装配、搭建、成套设备”在工程和创作圈子里它常被用来指代一套可组合的工具链或者工作台。前面加个 open意思就很明确了这是一套开放的、可自由拼装的工具集合而不是一个封闭的、只能按官方规定方式使用的黑盒产品。结合热搜词里高频出现的 claude code、codex、yaml、node.js 这几个关键词我基本能判断出 openrig 的定位它大概率是一个围绕 AI 编程助手claude code、codex 这类 CLI 工具搭建的本地配置与调度框架用 yaml 做配置描述用 node.js 做运行时支撑把多个模型端点、多个命令行工具、多套环境配置统一管理起来。说白了就是让你不用每次手动改一堆环境变量、不用在多个工具之间来回切换配置文件而是通过一份结构化的 yaml把“我要用哪个模型、走哪个端点、用哪个 CLI、传什么参数”一次性定义清楚。这个需求是真实存在的。我自己在同时使用 claude code 和 codex 的时候最头疼的就是两件事第一两个工具的配置格式不一样一个用 json一个用 toml 或者环境变量改来改去容易搞混第二切换模型端点的时候要改好几处地方稍不注意就出现 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错。openrig 如果能把这些问题收敛到一份 yaml 里那它的价值就很直接了降低配置心智负担减少切换成本让本地 AI 编程工作流更稳定。这篇文章适合几类人看一是已经在用 claude code 或 codex但被配置问题折腾得够呛的开发者二是想在自己机器上搭建一套可复用 AI 编程环境的进阶用户三是对 yaml 配置驱动、node.js 工具链感兴趣想看看别人怎么组织这类项目的人。下面我会从设计思路、核心细节、实操过程、问题排查几个角度把 openrig 这类项目该怎么做、怎么做稳完整拆一遍。2. 整体设计与思路拆解为什么是 yaml node.js 这套组合2.1 配置驱动优先把“状态”从脚本里抽出来很多人在搭建本地 AI 工具链时习惯写一堆 shell 脚本每个脚本里硬编码模型名称、端点地址、API 参数。这种做法短期能跑但一旦要换模型、换端点、换工具版本就得满世界找哪一行写了什么。openrig 这类项目如果采用 yaml 作为核心配置载体本质上是在做一件事把“环境状态”从“执行逻辑”里剥离出来。yaml 的好处在于结构清晰、层级直观、注释友好而且几乎每种语言都有成熟的解析库。对于 node.js 项目来说js-yaml 或者 yaml 这两个包都能稳定解析配合 schema 校验还能在启动前就发现配置错误。我实测下来用 yaml 描述多套 profile比如“本地 lmstudio 模式”“远程 deepseek 模式”“qwen 备用模式”比用环境变量清晰太多尤其是当你要同时管理 claude code 和 codex 两套工具时一份 yaml 里分区块定义阅读和维护成本都低得多。提示yaml 对缩进极其敏感建议统一用两个空格禁止 tab。很多“配置明明写了却不生效”的问题最后查出来都是缩进错位。2.2 node.js 作为运行时跨平台与生态成熟度选 node.js 做运行时理由也很实在。第一claude code 和 codex 的安装与使用本身就大量依赖 node.js 生态很多安装教程第一步就是“安装 node.js”“node.js lts 下载”“node.js 官网下载”说明这个技术栈已经是事实标准。第二node.js 的 child_process 模块可以很方便地调用外部 CLI 命令openrig 要调度 claude code 或 codex本质上就是拼参数、起进程、收输出。第三npm 生态里有大量现成的 yaml 解析、参数校验、日志输出库不用重复造轮子。我自己的经验是用 node.js 写这类调度工具最舒服的地方在于异步流程控制。比如你要先检查端点是否可达再启动 CLI再捕获输出并做后处理这一套用 async/await 写出来逻辑很顺。相比之下用纯 shell 写这些判断和重试可读性会差很多。2.3 多工具兼容claude code 与 codex 的差异收敛claude code 和 codex 虽然都是 AI 编程 CLI但它们的配置方式、参数命名、端点要求并不完全一致。热搜里出现的 “codex is ignoring 1 unrecognized configuration setting. check for typos or d” 和 “your organization has disabled claude subscription access for claude code” 就是典型例子一个是配置项拼写或位置不对一个是账号权限问题。openrig 的设计思路应该是在 yaml 里为每个工具定义独立的 adapter 区块把公共参数如模型名、端点、超时抽到顶层把工具特有参数放在各自区块里启动时由 node.js 脚本负责转换成对应工具能识别的格式。这样做的好处是当你从 claude code 切换到 codex 时不需要重新学一套配置语法只需要在 yaml 里切换 active profile 或者改一个字段。对于经常在多个模型之间切换的人来说这个设计能省下大量查文档的时间。2.4 安全与边界本地优先避免敏感信息硬编码这类项目还有一个容易被忽视的设计点密钥和端点信息的管理。我的建议是yaml 里只放结构不放明文密钥。密钥通过环境变量注入yaml 里用占位符引用。node.js 启动时读取环境变量并替换。这样即使配置文件被误提交到仓库也不会泄露敏感信息。同时端点地址尽量走本地回环或者内网地址减少不必要的网络暴露面。3. 核心细节解析与实操要点yaml 结构怎么设计才不踩坑3.1 一份可用的 openrig yaml 骨架下面这份结构是我根据常见实践整理出来的不是官方标准但可以直接拿来改。它的核心思想是顶层放全局默认值profiles 里放具体场景tools 里放各 CLI 的适配参数。version: 1 defaults: timeout: 120 retry: 2 log_level: info profiles: local-lmstudio: model: local-model endpoint: http://127.0.0.1:1234/v1 tool: claude-code remote-deepseek: model: deepseek-chat endpoint: https://api.example.com/v1 tool: codex api_key_env: DEEPSEEK_API_KEY tools: claude-code: bin: claude args: - --model - {{model}} env: BASE_URL: {{endpoint}} codex: bin: codex args: - --model - {{model}} env: OPENAI_BASE_URL: {{endpoint}} OPENAI_API_KEY: {{api_key}}这份配置里{{model}}、{{endpoint}}、{{api_key}}都是占位符由 node.js 在运行时替换。api_key_env指定从哪个环境变量读取密钥避免明文写入。tools区块里为每个 CLI 定义了可执行文件名、参数模板和环境变量映射。3.2 参数替换与校验启动前就把错误拦住node.js 脚本在读取 yaml 后第一件事应该是做 schema 校验。可以用ajv配合自定义 schema也可以用zod做运行时校验。校验内容包括version 是否存在、profiles 是否至少有一个、每个 profile 的 tool 是否在 tools 里有定义、endpoint 是否是合法 URL。这一步能拦掉大部分低级错误比如拼写错误、缺少必填字段。参数替换的逻辑要小心处理嵌套和转义。我的做法是写一个简单的递归替换函数遇到字符串就做占位符匹配遇到数组和对象就递归处理。替换完成后再检查是否还有未解析的占位符如果有就报错退出而不是带着{{model}}这种字面量去启动 CLI。注意不要用简单的字符串 replace 全局替换容易误伤。建议用正则/\{\{(\w)\}\}/g精确匹配占位符名称。3.3 进程调度child_process 的正确打开方式node.js 调用外部 CLI常用的是child_process.spawn或execFile。对于 claude code 和 codex 这种可能输出大量文本、需要实时看到日志的场景spawn更合适因为它支持流式读取 stdout 和 stderr。exec会把输出缓冲到内存输出量大时可能出问题。启动进程时环境变量要合并而不是覆盖。正确做法是{ ...process.env, ...toolEnv }这样既保留了系统原有的 PATH 等变量又注入了工具需要的端点信息。参数数组要避免 shell 注入直接传数组给spawn不要拼接成字符串再交给 shell。const { spawn } require(child_process); function runTool(tool, args, env) { return new Promise((resolve, reject) { const child spawn(tool.bin, args, { env: { ...process.env, ...env }, stdio: [inherit, pipe, pipe], }); child.stdout.on(data, (d) process.stdout.write(d)); child.stderr.on(data, (d) process.stderr.write(d)); child.on(error, reject); child.on(close, (code) { code 0 ? resolve() : reject(new Error(exit ${code})); }); }); }这段代码是我实际用过的简化版核心就是流式转发输出、正确合并环境变量、用退出码判断成败。3.4 超时与重试别让一次网络抖动毁掉整个流程AI 端点偶尔会超时尤其是走远程 API 的时候。openrig 应该在 yaml 里支持 timeout 和 retry 配置。实现上可以用Promise.race配合定时器做超时控制重试则用简单的循环加退避。退避策略建议用指数退避比如第一次等 1 秒第二次等 2 秒第三次等 4 秒避免短时间内反复冲击端点。但要注意不是所有错误都值得重试。像 “model is not supported” 这种配置错误重试多少次都没用应该直接失败并给出明确提示。只有网络超时、连接被拒这类临时性错误才适合重试。4. 实操过程与核心环节实现从零搭起一套可跑的 openrig4.1 环境准备node.js 安装与版本选择第一步是装 node.js。官网下载页面有 LTS 和 Current 两个版本我的建议是选 LTS。热搜里出现过 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava” 这种报错通常是因为指定了一个不存在的版本号或者镜像源还没同步。稳妥做法是去 node.js 官网下载 LTS 安装包或者用 nvm 这类版本管理工具安装。Ubuntu 上可以用 apt 装但 apt 源里的版本往往偏旧。我更推荐用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v装完后确认node -v和npm -v都能正常输出。如果公司网络对某些域名有限制可以配置 npm 镜像源但要注意镜像源的同步延迟别用太冷门的源。4.2 初始化项目与安装依赖新建目录初始化 npm 项目安装核心依赖mkdir openrig cd openrig npm init -y npm install yaml zodyaml负责解析配置文件zod负责校验结构。如果你想要更友好的命令行交互可以再加commander或yargs。日志输出可以用pino或直接 console看个人喜好。目录结构建议这样组织openrig/ config/ openrig.yaml src/ index.js loader.js runner.js validator.js package.jsonloader.js负责读 yamlvalidator.js负责校验runner.js负责调度进程index.js是入口。4.3 编写配置加载与校验逻辑loader.js的核心逻辑const fs require(fs); const path require(path); const YAML require(yaml); function loadConfig(filePath) { const abs path.resolve(filePath); if (!fs.existsSync(abs)) { throw new Error(config not found: ${abs}); } const raw fs.readFileSync(abs, utf8); return YAML.parse(raw); } module.exports { loadConfig };validator.js用 zod 定义 schemaconst { z } require(zod); const ProfileSchema z.object({ model: z.string(), endpoint: z.string().url(), tool: z.string(), api_key_env: z.string().optional(), }); const ConfigSchema z.object({ version: z.number(), defaults: z.object({ timeout: z.number().default(120), retry: z.number().default(2), log_level: z.string().default(info), }), profiles: z.record(ProfileSchema), tools: z.record(z.object({ bin: z.string(), args: z.array(z.string()).default([]), env: z.record(z.string()).default({}), })), }); module.exports { ConfigSchema };校验失败时zod 会给出具体哪个字段不匹配比手写 if-else 清晰得多。4.4 实现参数替换与进程启动替换函数要处理字符串、数组、对象三种情况function interpolate(value, ctx) { if (typeof value string) { return value.replace(/\{\{(\w)\}\}/g, (_, key) { if (ctx[key] undefined) { throw new Error(missing placeholder: ${key}); } return ctx[key]; }); } if (Array.isArray(value)) { return value.map((v) interpolate(v, ctx)); } if (value typeof value object) { const out {}; for (const [k, v] of Object.entries(value)) { out[k] interpolate(v, ctx); } return out; } return value; }启动时先根据 profile 名找到配置构造上下文对象包含 model、endpoint、api_key 等然后对 tool 的 args 和 env 做替换最后调用runTool。4.5 实际运行与验证假设 yaml 里配置了local-lmstudio这个 profile运行命令可以是node src/index.js --profile local-lmstudio --prompt 帮我写一个快速排序脚本会读取配置、校验、替换参数、启动对应的 CLI并把输出实时打印到终端。如果一切正常你应该能看到 claude code 或 codex 的交互界面并且它使用的是你指定的本地端点。我实测下来这套流程在 Ubuntu 和 Windows 上都能跑通Windows 上需要注意路径分隔符和可执行文件后缀.cmd可以用cross-spawn这个包来抹平差异。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 配置类问题速查表现象可能原因排查方向codex is ignoring 1 unrecognized configuration setting配置项拼写错误或放错层级检查 yaml 缩进和字段名对照工具文档cc switch local proxy failed while handling codex endpoint /responses端点地址不对或代理未启动确认 endpoint 可达检查本地服务是否运行model is not supported when using codex模型名与工具要求不匹配确认该工具支持的模型列表your organization has disabled claude subscription access账号权限或订阅状态问题检查账号设置确认是否有访问权限启动后无输出或卡住进程 stdio 配置不当检查 spawn 的 stdio 参数确保 stdout 被消费5.2 端点连通性排查遇到连接问题时先用 curl 或浏览器直接访问端点确认服务本身是活的。比如本地 lmstudio 的端点可以在浏览器里访问http://127.0.0.1:1234/v1/models看是否返回模型列表。如果 curl 能通但 openrig 不通那问题多半在环境变量注入或参数替换环节。提示环境变量名大小写敏感Linux 和 Windows 行为一致但某些工具会读取特定前缀的变量务必对照文档确认。5.3 版本兼容性坑node.js 版本太新或太旧都可能导致依赖装不上。热搜里那个 “node.js v24.21.0 is not yet released” 就是典型。我的建议是锁定 LTS 大版本比如 20.x 或 22.x在 package.json 里用 engines 字段声明{ engines: { node: 20 23 } }这样团队成员装错版本时npm 会给出警告。5.4 日志与调试技巧openrig 这类工具日志分级很重要。默认 info 级别只输出关键步骤排查问题时切到 debug把替换后的参数、环境变量、进程退出码都打出来。但要注意debug 日志里不要打印完整密钥只打印前几位加星号。我自己的习惯是在 runner 里加一个--dry-run选项只做配置加载、校验、参数替换不真正启动进程把最终要执行的命令和环境变量打印出来。这个功能在排查“为什么参数没生效”时特别有用。5.5 多 profile 切换的实操心得如果你经常在本地模型和远程模型之间切换建议在 yaml 里把公共部分抽到 defaultsprofile 里只写差异。切换时只改--profile参数不要手动改 yaml。我试过把 profile 名做成快捷命令比如alias rig-localnode src/index.js --profile local-lmstudio用起来很顺手。另外不同 profile 的端点如果同时可用可以考虑做健康检查启动前先 ping 一下不可用就自动 fallback 到备用 profile。这个逻辑用 node.js 写起来不复杂但能显著提升日常使用的流畅度。6. 扩展方向openrig 还能怎么玩这套框架搭起来之后扩展空间其实很大。一个方向是加插件机制让 tools 区块支持自定义脚本比如在启动 CLI 前先跑一段预处理或者在输出后做格式化。另一个方向是加会话管理把每次调用的 prompt、模型、输出存到本地 sqlite方便回溯和对比不同模型的表现。还有一个我觉得很实用的扩展是模板库。把常用的 prompt 模板放到 yaml 或者单独目录里通过变量注入生成最终 prompt。比如“代码审查”“单元测试生成”“重构建议”各做一个模板调用时只传文件路径和模板名。这样能把重复性的提示词工作也收敛到配置里进一步减少手动输入。如果你在用 vscode还可以考虑做一个简单的任务集成把 openrig 的常用 profile 注册成 vscode task一键触发。vscode 配置 claude code 和 codex 的教程网上已经很多但把两者统一到一个入口的还比较少openrig 正好补上这个位置。我在实际使用中最大的体会是工具链的稳定性不取决于单个工具多强而取决于它们之间的衔接是否顺滑。openrig 这类项目的价值就在于把衔接处的摩擦降到最低。配置写一次后面切换模型、切换工具、切换端点都只是改一个字段的事。这种“一次投入、长期省心”的买卖对每天都要和 AI 编程助手打交道的人来说很划算。