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. 实操过程与核心环节实现：从零搭起一套可跑的 openrig

4.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 源里的版本往往偏旧。我更推荐用 nvm：

curl -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 zod

yaml负责解析配置文件，zod负责校验结构。如果你想要更友好的命令行交互，可以再加commander或yargs。日志输出可以用pino或直接 console，看个人喜好。

目录结构建议这样组织：

openrig/ config/ openrig.yaml src/ index.js loader.js runner.js validator.js package.json

loader.js负责读 yaml，validator.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 定义 schema：

const { 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 配置类问题速查表

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 里把公共部分抽到 defaults，profile 里只写差异。切换时只改--profile参数，不要手动改 yaml。我试过把 profile 名做成快捷命令，比如alias rig-local='node 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 编程助手打交道的人来说，很划算。