1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架项目毕竟 rig 在英文里常指设备支架、装配架。但结合 Claude Code、Codex、YAML、Node.js 这几个关键词放在一起方向就很清楚了——这是一个围绕 AI 编程助手Coding Agent做统一配置与编排的工具。简单说openrig 想干的事情是把散落在各个 AI 编程工具里的配置、模型接入、环境变量、启动参数收敛到一套可维护的结构里让你在 Claude Code、Codex 这类 CLI 工具之间切换时不用每次手动改一堆东西。我接触这类工具是因为一个很现实的痛点。手头同时用着 Claude Code 和 Codex前者在终端里跑得顺后者在某些任务上表现更稳但两者的配置格式、环境变量命名、模型指定方式都不一样。每次换工具要么改 shell 配置文件要么临时 export 一堆变量时间长了配置文件乱成一团自己都记不清哪个变量是给谁用的。openrig 这类工具的价值就在于把这些碎片统一管理用一份 YAML 描述清楚我要用哪个模型、走哪个端点、带哪些参数然后由工具负责翻译成各个 CLI 能识别的形式。适合读这篇内容的人大概有三类。第一类是刚上手 Claude Code 或 Codex 的新手被安装、配置、模型接入这些环节卡住想找个系统性的思路。第二类是已经在用多个 AI 编程工具的老手配置管理开始变得混乱需要一套结构化的方案。第三类是对 Node.js 生态熟悉、想自己动手做配置编排的开发者openrig 的设计思路本身就有参考价值。不管你是哪一类核心诉求都一样让工具服务于人而不是人被工具的各种配置细节拖着走。需要提前说明的是openrig 目前并不是一个官方标准更多是社区里围绕 AI 编程工具配置管理形成的一类实践思路。所以下面讲的内容既有对这类工具通用设计逻辑的拆解也有具体到 YAML 结构、Node.js 环境、CLI 参数的可落地操作。你完全可以照着做也可以只取其中对你有用的部分。2. 核心设计思路为什么用 YAML 加 Node.js 这套组合2.1 配置与执行分离的基本逻辑openrig 这类工具最核心的设计思想是把配置和执行拆开。配置层用 YAML 描述意图执行层用 Node.js 脚本把意图翻译成具体命令。这个拆分看起来简单但它解决了一个长期困扰多工具用户的问题配置的可读性和可维护性。传统的做法是把配置写进 shell 的 rc 文件比如.bashrc或.zshrc里面塞满export ANTHROPIC_API_KEYxxx、export OPENAI_BASE_URLyyy这样的行。问题是这些行是扁平的没有结构工具一多就分不清哪行属于哪个工具。而且 shell 变量是全局的改一个可能影响另一个。YAML 的好处是天然支持层级结构你可以这样组织profiles: claude-work: tool: claude-code model: claude-sonnet endpoint: https://api.example.com env: API_KEY: ${CLAUDE_KEY} codex-local: tool: codex model: gpt-5.6-sol endpoint: http://localhost:1234/v1 env: API_KEY: local这种结构一眼就能看出每个 profile 属于哪个工具、用什么模型、走哪个端点。想切换的时候只要指定 profile 名字就行不用手动改环境变量。这就是配置与执行分离带来的直接好处。2.2 为什么选 Node.js 作为执行层选 Node.js 做执行层不是随便定的。Claude Code 和 Codex 这两个工具本身就是 Node.js 生态的产物它们的 CLI 通过 npm 分发运行依赖 Node 运行时。用 Node.js 写编排脚本能直接复用这些工具已有的依赖和调用方式不用额外引入 Python 或 Go 的运行时。另一个原因是 Node.js 处理子进程和流式输出很顺手。AI 编程工具的输出往往是流式的需要实时把 stdout 转发到终端。Node.js 的child_process.spawn配合流处理几行代码就能做到。而且 npm 生态里有大量现成的 YAML 解析库比如js-yaml解析配置文件这件事基本是开箱即用。还有一点是跨平台。Claude Code 和 Codex 在 Windows、macOS、Linux 上都能跑Node.js 同样三平台通吃。用 Node.js 写编排层一套代码三个平台都能用不用为 Windows 单独写批处理。这对需要在不同机器上同步配置的人来说很关键。2.3 方案选型的取舍与边界这套组合也不是没有代价。Node.js 的启动有一定开销如果你只是想在 shell 里快速跑个命令多一层 Node 脚本会慢那么一两百毫秒。对于交互式使用这点延迟基本感知不到但如果是脚本里批量调用累积起来就明显了。所以 openrig 这类工具通常只用在启动会话这种低频操作上不会嵌到高频循环里。YAML 本身也有坑。它对缩进极其敏感一个空格错位就解析失败而且报错信息经常指向莫名其妙的位置。新手第一次写 YAML 配置十有八九会栽在缩进上。后面我会专门讲怎么排查这类问题。另外 YAML 的隐式类型转换也容易出意外比如model: 1.0会被解析成浮点数而不是字符串这种细节在配置模型名的时候要特别注意。3. 环境准备Node.js 与工具链的正确安装姿势3.1 Node.js 版本选择与安装openrig 依赖 Node.js所以第一步是把 Node 环境弄对。这里有个高频踩坑点网上搜node.js 下载出来的结果五花八门有人下到官网的 Current 版本有人下到 LTS 版本还有人从各种第三方站点下到改过的包。我的建议是只从 Node.js 官网下载 LTS 版本Current 版本虽然新但可能和某些工具的依赖不兼容。LTS 是长期支持版的意思稳定性和兼容性都经过验证。截至我写这篇内容时Node 20 和 Node 22 的 LTS 都是安全选择。安装方式上macOS 和 Linux 用户我更推荐用版本管理工具比如nvm这样可以在不同项目间切换 Node 版本不会因为全局装了一个版本导致别的项目跑不起来。# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 或 ~/.zshrc # 安装并使用 Node 20 LTS nvm install 20 nvm use 20 nvm alias default 20Windows 用户可以用nvm-windows或者直接下官网的 LTS 安装包。安装完记得验证node -v npm -v两条命令都能正常输出版本号说明环境没问题。如果node -v报command not found多半是 PATH 没配好重启终端或者检查安装时是否勾选了添加到 PATH。注意网上流传的某些 Node.js 版本号比如 24.21.0可能根本还没发布。如果你在安装时看到 node.js v24.21.0 is not yet released or is not available 这类报错说明你指定的版本不存在换成官网列出的实际 LTS 版本即可。3.2 Claude Code 与 Codex 的安装Node 环境就绪后装 Claude Code 和 Codex 就简单了。两者都是通过 npm 全局安装# 安装 Claude Code npm install -g anthropic-ai/claude-code # 安装 Codex npm install -g openai/codex装完验证claude --version codex --version如果提示权限错误Linux/macOS 上常见不要直接sudo npm install那样会把文件装到 root 名下后续更新会出权限问题。正确做法是配置 npm 的全局目录到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到.bashrc或.zshrc里然后重新安装。3.3 编辑器侧的配置如果你用 VS Code装 Claude Code 或 Codex 的扩展能省不少事。VS Code 里配置 Claude Code 的关键是让扩展能找到 CLI 的可执行文件路径。有时候扩展装了但用不了报找不到 claude 命令就是因为 VS Code 的集成终端 PATH 和系统终端不一致。解决办法是在 VS Code 的settings.json里显式指定路径{ claude-code.executablePath: /Users/yourname/.npm-global/bin/claude }Windows 上路径类似C:\\Users\\yourname\\.npm-global\\claude.cmd。这个细节官方文档里不一定写但实际配置时经常遇到。4. openrig 配置文件的完整写法与实操4.1 YAML 配置文件的结构设计openrig 的核心是一份 YAML 配置文件通常放在项目根目录或者用户主目录下命名类似openrig.yaml或.openrig/config.yaml。这份文件要描述清楚几件事有哪些工具、每个工具用哪个模型、走哪个端点、需要哪些环境变量。一个完整的配置结构大概长这样version: 1 defaults: timeout: 120 retries: 2 profiles: claude-default: tool: claude-code model: claude-sonnet-4 endpoint: https://api.anthropic.com env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} args: - --dangerously-skip-permissions codex-default: tool: codex model: gpt-5.6-sol endpoint: https://api.openai.com/v1 env: OPENAI_API_KEY: ${OPENAI_API_KEY} codex-local: tool: codex model: local-model endpoint: http://localhost:1234/v1 env: OPENAI_API_KEY: local-no-key args: - --no-stream这里有几个设计要点值得说。version字段是为了将来配置格式升级时做兼容现在写 1 就行。defaults放全局默认值比如超时和重试次数各个 profile 可以覆盖。profiles下面是具体的配置块每个块有tool、model、endpoint、env、args五个主要字段。env里的${ANTHROPIC_API_KEY}是变量引用语法意思是从当前 shell 环境里读这个变量的值。这样做的好处是密钥不落在配置文件里配置文件可以放心提交到版本控制。如果你把密钥直接写进 YAML那这份文件就绝对不能进 git 了。4.2 模型接入的几种典型场景模型接入是配置里最容易出问题的部分因为不同工具的 API 格式不一样。Claude Code 走的是 Anthropic 的接口格式Codex 走的是 OpenAI 兼容格式。如果你想用第三方模型比如 DeepSeek、Qwen、GLM就得看它们提供的是哪种兼容接口。以接入一个 OpenAI 兼容的第三方模型为例配置大概是这样profiles: codex-deepseek: tool: codex model: deepseek-chat endpoint: https://api.deepseek.com/v1 env: OPENAI_API_KEY: ${DEEPSEEK_API_KEY}关键点是endpoint要指向第三方服务的地址model填对方支持的模型名。有些第三方服务虽然兼容 OpenAI 格式但模型名和官方不一样填错了会报model not supported。比如你看到{detail:the gpt-5.6-sol model is not supported when using codex with a...}这种报错就是模型名和端点不匹配检查一下你用的端点到底支持哪些模型名。本地模型接入也是类似逻辑。如果你在本地跑了一个推理服务监听在http://localhost:1234/v1那endpoint就填这个地址model填本地服务加载的模型名API_KEY随便填个占位符就行本地服务一般不校验。4.3 环境变量的管理与注入环境变量的管理是 openrig 这类工具的核心价值之一。传统做法是手动 export容易漏、容易错。openrig 的做法是在启动时根据 profile 自动注入。实现上Node.js 脚本读取 YAML 后把env字段里的变量合并到子进程的环境里const { spawn } require(child_process); const yaml require(js-yaml); const fs require(fs); function loadProfile(profileName) { const config yaml.load(fs.readFileSync(./openrig.yaml, utf8)); return config.profiles[profileName]; } function resolveEnv(envConfig) { const resolved {}; for (const [key, value] of Object.entries(envConfig || {})) { // 处理 ${VAR} 形式的引用 const match String(value).match(/^\$\{(\w)\}$/); if (match) { resolved[key] process.env[match[1]] || ; } else { resolved[key] value; } } return resolved; } function run(profileName, extraArgs []) { const profile loadProfile(profileName); const env { ...process.env, ...resolveEnv(profile.env) }; const args [...(profile.args || []), ...extraArgs]; const child spawn(profile.tool, args, { env, stdio: inherit }); child.on(exit, code process.exit(code)); } run(process.argv[2], process.argv.slice(3));这段代码虽然短但把核心逻辑都包含了读配置、解析变量引用、合并环境、启动子进程、转发退出码。stdio: inherit是关键它让子进程直接接管终端交互式输入输出都能正常工作。提示resolveEnv里对${VAR}的处理只匹配了整行是变量引用的简单情况。如果你的配置里需要前缀变量这种拼接比如Bearer ${TOKEN}正则要相应调整用replace而不是match。5. 常见问题排查与避坑实录5.1 YAML 解析报错怎么定位YAML 报错是新手最头疼的。典型症状是启动时报一堆看不懂的解析错误指向的行号还不对。原因通常是缩进用了 Tab 而不是空格或者冒号后面没加空格。排查方法很直接用在线 YAML 校验工具或者命令行工具先验证一遍。# 用 Node.js 快速验证 YAML 是否合法 node -e require(js-yaml).load(require(fs).readFileSync(openrig.yaml,utf8)); console.log(OK)如果报错它会告诉你具体哪一行有问题。常见错误对照表报错信息常见原因解决办法bad indentation of a mapping entry缩进不一致或用了 Tab统一用 2 空格缩进could not find expected :冒号后缺空格写成key: value而非key:valueduplicated mapping key同一个 key 写了两遍检查是否有重复的 profile 名unacceptable character有不可见字符用编辑器显示空白字符排查我踩过最坑的一次是复制粘贴配置时带进了全角空格肉眼看和普通空格一模一样但 YAML 就是不认。后来养成习惯配置写完先跑一遍校验省得启动时才发现。5.2 模型不支持的报错处理model is not supported这类报错根源是模型名和端点不匹配。排查顺序是先确认端点地址对不对再确认模型名是不是该端点支持的。有些第三方服务会在文档里列出支持的模型名但实际接口返回的模型名可能带版本后缀。比如文档写deepseek-chat实际要填deepseek-chat-v3。这种情况最靠谱的办法是直接调一次接口看返回curl -s https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY | head -50返回的列表里就是实际可用的模型名照着填准没错。5.3 组织权限相关的报错用 Claude Code 时可能遇到your organization has disabled claude subscription access for claude code这类提示。这不是配置问题是账号权限问题。通常出现在企业账号上管理员关闭了某个功能的访问。遇到这种情况配置层面怎么改都没用得从账号权限入手或者换用个人账号。Codex 那边也有类似情况报codex无法加载组织设置。同样是权限层面的问题检查账号是否有对应权限或者是不是登录状态失效了。重新登录一次往往能解决。5.4 本地代理与端点切换的坑配置里最容易出问题的是端点切换。比如你本来用官方端点想切到本地模型改了endpoint但忘了改model就会报模型不支持。或者本地服务没启动连接被拒绝。排查这类问题的思路是分层验证先确认本地服务在跑curl http://localhost:1234/v1/models再确认配置里的端点地址和端口对得上最后确认模型名是本地服务加载的那个。三层都对基本就能通。还有一种情况是代理配置残留。如果你之前配过 HTTP 代理环境变量HTTP_PROXY还在请求会被转发到代理导致连不上本地服务。检查一下env | grep -i proxy如果有输出临时清掉再试unset HTTP_PROXY HTTPS_PROXY6. 进阶玩法多工具协同与配置复用6.1 用 profile 继承减少重复配置写多了会发现很多字段是重复的。比如所有 Claude 相关的 profile 都用同一个 API key所有本地模型的 profile 都用同一个端点。这时候可以用 YAML 的锚点和引用来复用_anchors: claude_base: claude_base tool: claude-code endpoint: https://api.anthropic.com env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} profiles: claude-fast: : *claude_base model: claude-haiku claude-strong: : *claude_base model: claude-opusclaude_base定义锚点*claude_base引用:是合并键。这样两个 profile 共享基础配置只覆盖不同的模型名。改 API key 的时候只改一处所有引用它的 profile 都跟着变。6.2 在多个工具间共享会话上下文Claude Code 和 Codex 各有各的会话历史默认不互通。但如果你在做同一个项目希望两个工具都能看到之前的上下文可以把项目相关的说明写进一个共享文件比如PROJECT.md然后在两个工具的配置里都指向它。Claude Code 支持通过CLAUDE.md加载项目上下文Codex 也有类似的机制。你可以在 openrig 的配置里加一个步骤启动前把共享的上下文文件软链接或复制到各工具期望的位置。这样切换工具时上下文不会断。6.3 配置的版本管理与团队共享openrig 配置最大的好处之一是可以进版本控制。把openrig.yaml提交到项目仓库团队成员拉下来就能用同一套配置。密钥通过环境变量注入不落在文件里安全性和便利性兼顾。团队共享时建议加一个openrig.example.yaml里面用占位符代替真实密钥新成员复制一份改名后填自己的密钥。这样既降低了上手门槛又避免了密钥泄露。注意.gitignore里一定要加上真实的配置文件如果它包含密钥和任何本地覆盖文件。团队协作时个人覆盖配置用openrig.local.yaml这种命名主配置只放共享部分。7. 我实际用下来的一些体会openrig 这类工具的价值用过一段时间才能真正体会到。刚开始你可能觉得多一层配置麻烦不如直接 export 变量来得快。但当你的工具从 1 个变成 3 个模型从 1 个变成 5 个配置从 10 行变成 100 行的时候结构化管理带来的收益就显现出来了。我自己的做法是把 openrig 配置和项目绑定每个项目根目录放一份里面定义这个项目常用的几个 profile。切项目的时候cd进去配置自动生效不用记这个项目用的是哪个模型。这个习惯养成后切换工具的心理负担小了很多愿意尝试新工具的频率也高了。最后分享一个小技巧给常用的 profile 起短名字然后在 shell 里加个别名。比如alias ccnode openrig.js claude-default敲cc就能启动。名字越短用起来越顺手配置管理这件事才不会变成负担。