1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里就是“装配、机架”的意思。但结合 Claude Code、Codex、YAML、Node.js 这几个热搜词一起看方向就很清楚了——这是一个围绕 AI 编程助手工具链做统一配置与编排的开源项目。说白了它想解决的是同一个开发者同时用 Claude Code、Codex 这类命令行 AI 助手时配置散落各处、切换成本高、环境难复现的问题。我自己的日常就是 Claude Code 和 Codex 混着用。Claude Code 在长上下文重构和终端命令执行上很顺手Codex 在处理某些特定端点和本地模型接入时又有它的优势。但两套工具各有各的配置文件、各有各的环境变量、各有各的模型端点设置时间一长光是记住“这个参数配在哪个文件里”就够头疼的。openrig 的价值就在于把这些东西收敛到一套以 YAML 为核心的声明式配置里用 Node.js 作为运行时把它们串起来。这篇文章适合三类人看第一类是刚接触 Claude Code 或 Codex还在纠结怎么安装、怎么配置的新手第二类是已经在用但配置管理一团乱麻、想找一套统一方案的老手第三类是对 YAML 配置驱动、Node.js 工具链感兴趣想看看别人怎么设计这类编排系统的开发者。我会从整体设计思路讲到具体实操把踩过的坑和验证过的参数都摊开来说。2. 整体设计与思路拆解2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为核心配置格式这个决定背后有很实际的考量。JSON 不支持注释而 AI 助手工具的配置里经常需要标注“这个 key 是从哪拿的”“这个端点什么时候用”没有注释简直是灾难。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述多个模型端点、多套工具配置的时候层级一深就不好读。YAML 的优势在于它对嵌套和列表的表达非常自然。比如你要配置三个不同的模型端点每个端点有自己的 base_url、api_key 引用、模型名、超时时间用 YAML 写出来是一棵清晰的树肉眼扫一遍就知道结构。而且 YAML 支持锚点和引用同一份 api_key 配置可以在多个地方复用改一处就全改这在多工具共享凭证的场景下特别省事。提示YAML 对缩进极其敏感Tab 和空格混用会直接报解析错误。我建议统一用两个空格缩进并且在编辑器里开启“显示空白字符”这样能一眼看出缩进问题。2.2 Node.js 作为运行时的取舍用 Node.js 做运行时而不是 Python 或 Go核心原因是生态契合。Claude Code 和 Codex 这类工具的官方分发和社区工具链大量基于 npm安装、升级、插件管理都走 npm 这一套。openrig 用 Node.js 写意味着它可以直接复用 npm 的依赖管理能力用户装的时候一条npm install就搞定不需要额外折腾 Python 虚拟环境或者 Go 的编译工具链。另一个原因是跨平台一致性。Node.js 在 Windows、macOS、Linux 上的行为差异相对小尤其是文件路径处理、环境变量读取这些和配置编排强相关的操作Node.js 的抽象层做得比较统一。我自己在 Windows 和 Ubuntu 上都跑过同一份 openrig 配置基本不用改就能两边通用这点比某些依赖系统 shell 的脚本方案强太多。当然 Node.js 也有代价就是版本管理。热搜里出现的 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型的版本坑——你照着某个教程敲命令结果那个版本号根本不存在或者还没发布。我的经验是永远用 LTS 版本去 Node.js 官网下载页认准 “LTS” 标记不要追最新的奇数版本。2.3 统一编排解决的核心痛点在没有 openrig 这类工具之前我的配置状态是这样的Claude Code 的配置在一个隐藏目录里Codex 的配置在另一个地方本地模型接入比如通过 LM Studio 起的本地端点又是第三处配置。每次换机器或者重装系统我都要凭记忆把这些配置重新拼一遍经常漏掉某个环境变量然后花半小时排查为什么工具连不上。openrig 的思路是把这些配置抽象成“声明式的单一事实来源”。你在一份 YAML 里描述清楚我要用哪些工具、每个工具连哪个端点、用哪个模型、凭证从哪个环境变量读。openrig 负责把这份声明翻译成各个工具能识别的实际配置。这样换机器时你只需要带走一份 YAML 和对应的环境变量剩下的交给 openrig 生成。这个设计还有一个隐性好处配置可以进版本控制。把 YAML 提交到私有仓库团队里每个人拉下来就能得到一致的 AI 助手环境。以前这种一致性只能靠文档口口相传现在变成了代码。3. 核心细节解析与实操要点3.1 环境准备Node.js 安装的正确姿势一切从 Node.js 开始。Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包双击一路下一步即可安装程序会自动把 node 和 npm 加进 PATH。macOS 用户我强烈建议用 nvm 管理版本因为 macOS 上直接用安装包容易和系统自带的 node 冲突nvm 可以让你在不同项目间自由切换版本。Ubuntu 用户注意不要用apt install nodejs那个版本通常很旧。正确做法是先装 nvm再用 nvm 装 LTScurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts装完之后验证node -v npm -v两个命令都能输出版本号说明环境就绪。如果node -v报 command not found八成是 PATH 没配好检查一下 nvm 的初始化脚本有没有写进你的 shell 配置文件。注意热搜里那个 “node.js v24.21.0 is not yet released” 的错误本质是你指定的版本号在官方仓库里不存在。解决办法很简单用nvm install --lts让 nvm 自己挑最新的 LTS不要手写版本号。3.2 YAML 配置文件的结构设计openrig 的 YAML 配置我建议按“全局设置 工具列表 端点定义”三层来组织。全局设置放一些通用项比如日志级别、默认超时工具列表描述你要启用哪些助手端点定义把模型服务的连接信息集中管理。一个典型的骨架长这样version: 1 global: log_level: info timeout: 30 endpoints: - name: local-lmstudio base_url: http://127.0.0.1:1234/v1 api_key_env: LMSTUDIO_KEY models: - qwen2.5-coder - deepseek-coder tools: - name: claude-code endpoint: local-lmstudio model: qwen2.5-coder - name: codex endpoint: local-lmstudio model: deepseek-coder这里的关键设计是api_key_env字段。它不直接写密钥而是写一个环境变量的名字运行时从环境里读。这样做的好处是 YAML 可以安全地进版本控制密钥留在环境变量或者本地的 .env 文件里不会泄露。3.3 端点与模型的映射逻辑端点定义里我特意把 models 做成列表因为一个端点比如本地 LM Studio往往同时加载了好几个模型。工具配置里通过endpointmodel两个字段来定位具体用哪个。这种解耦的好处是当你想把某个工具从本地模型切到远程模型时只需要改工具配置里的 endpoint 引用不用动端点定义本身。实操中我发现一个容易忽略的点不同工具对模型名的要求不一样。Claude Code 可能期望模型名带特定前缀Codex 可能对模型名有白名单校验。openrig 在这层做了一层映射你可以在工具配置里加一个model_alias字段把统一模型名翻译成工具认识的写法tools: - name: codex endpoint: local-lmstudio model: deepseek-coder model_alias: deepseek-coder-v2这样上层配置保持统一底层适配交给 alias 处理。3.4 环境变量的管理策略环境变量是这套方案里最容易出问题的地方。我的做法是分两层系统级环境变量放长期不变的凭证项目级 .env 文件放和当前项目相关的配置。openrig 启动时会先读系统环境再读项目目录下的 .env后者覆盖前者。.env 文件格式很简单LMSTUDIO_KEYsk-local-xxxx REMOTE_API_KEYsk-remote-yyyy提示.env 文件一定要加进 .gitignore这是血泪教训。我见过有人把带真实密钥的 .env 提交到公开仓库结果密钥被扫走滥用。4. 实操过程与核心环节实现4.1 从零搭建 openrig 环境的完整流程假设你是一台全新的 Ubuntu 机器从零开始。第一步装 nvm 和 Node.js LTS前面已经讲过。第二步创建项目目录并初始化mkdir my-ai-rig cd my-ai-rig npm init -y npm install openrig第三步创建配置文件目录结构mkdir -p config touch config/openrig.yaml touch .env第四步把前面那套 YAML 骨架写进 config/openrig.yaml把密钥写进 .env。第五步在 package.json 里加一个启动脚本{ scripts: { rig: openrig apply --config config/openrig.yaml } }然后npm run rig就能把配置应用到各个工具。第一次跑的时候 openrig 会检测哪些工具已安装、哪些配置需要写入输出一份变更清单让你确认。4.2 Claude Code 的接入细节Claude Code 的接入有两个关键点。一是安装官方推荐的方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code装完之后claude命令应该可用。二是配置Claude Code 默认会读用户目录下的配置文件openrig 的作用就是帮你生成这份文件。如果你在 VS Code 里用 Claude Code 插件还需要在 VS Code 的设置里指向 openrig 生成的配置路径。我实测下来Claude Code 对本地模型的支持需要端点兼容 OpenAI 的 chat completions 接口。LM Studio 默认就提供这个接口起服务的时候记得在设置里打开 “Serve on Local Network” 或者至少确认端口是 1234。如果 Claude Code 报连接失败先用 curl 测一下端点通不通curl http://127.0.0.1:1234/v1/models能返回模型列表说明端点没问题问题在 Claude Code 的配置侧。4.3 Codex 的接入与端点适配Codex 的接入稍微复杂一点因为它对端点的路径有要求。热搜里那个 “cc switch local proxy failed while handling codex endpoint /responses” 就是典型的端点路径不匹配问题。Codex 期望的端点路径是/responses而很多本地服务默认只提供/v1/chat/completions。解决办法是在 openrig 的端点定义里加一个路径重写规则endpoints: - name: local-lmstudio base_url: http://127.0.0.1:1234/v1 path_rewrite: /responses: /chat/completions这样 Codex 发往/responses的请求会被重写到/chat/completions本地服务就能正常处理了。这个重写逻辑是 openrig 在中间层做的对上层工具透明。Codex 的安装同样走 npmnpm install -g openai/codex装完codex命令可用。第一次运行会让你登录或者配置 API key如果你用本地模型选择“自定义端点”然后填 openrig 暴露的本地地址。4.4 本地模型接入的完整链路验证整条链路是Codex/Claude Code → openrig 代理层 → LM Studio 本地服务。验证的时候从后往前查。先确认 LM Studio 在跑curl http://127.0.0.1:1234/v1/models有输出。再确认 openrig 代理层在跑curl http://127.0.0.1:8080/v1/models有输出。最后在 Codex 里发一条简单消息看能不能收到回复。我踩过的一个坑是端口冲突。openrig 默认监听 8080但 8080 经常被其他服务占用。解决办法是在 YAML 的 global 段里改端口global: proxy_port: 18080改完记得同步更新工具配置里的端点地址。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错安装阶段最高频的问题就是 Node.js 版本。除了前面说的版本号不存在还有一种情况是版本太低。openrig 和它依赖的一些包可能要求 Node.js 18 以上如果你系统里是 16装的时候会报 engine 不兼容。解决办法就是nvm install --lts然后nvm use --lts。另一个常见问题是 npm 权限。在 Linux 上如果不用 nvm 而是用系统包管理器装的 node全局安装时可能报 EACCES 权限错误。这时候不要用 sudo 硬装正确做法是配置 npm 的全局目录到用户目录下npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH5.2 配置解析失败的排查思路YAML 解析失败是最让人抓狂的因为报错信息往往只告诉你“某行有问题”不告诉你具体哪里错了。我的排查顺序是先看缩进再看特殊字符最后看编码。缩进问题用编辑器的显示空白字符功能一眼就能看出来。特殊字符主要是冒号和引号YAML 里值如果包含冒号必须用引号包起来否则会被当成键值分隔符。编码问题比较隐蔽Windows 上某些编辑器默认存成 GBKYAML 解析器读的时候会乱码。统一存成 UTF-8 无 BOM 格式就能避免。5.3 端点连接问题的速查表现象可能原因排查方法连接被拒绝本地服务没起或端口不对curl 测端点404 路径错误端点路径不匹配检查 path_rewrite401 未授权api_key 没读到检查环境变量名超时模型加载慢或超时太短调大 timeout模型不存在模型名不匹配检查 model_alias这张表是我自己遇到问题后总结的基本覆盖了九成以上的连接故障。按表排查比盲目改配置高效得多。5.4 多工具共存时的冲突处理Claude Code 和 Codex 同时跑的时候最容易冲突的是端口和配置文件路径。我的做法是给每个工具分配独立的代理端口在 openrig 的 tools 配置里显式指定tools: - name: claude-code proxy_port: 18081 - name: codex proxy_port: 18082配置文件路径同理openrig 会为每个工具生成独立的配置片段避免互相覆盖。这一点在团队协作时尤其重要因为不同人可能用不同的工具组合独立配置能保证互不干扰。6. 我在这套方案上的一些实战体会用 openrig 这套思路管理 AI 助手配置最大的收益不是省了多少时间而是把“环境”变成了可复制的东西。以前换机器要折腾半天现在一份 YAML 加一个 .env 就搞定。而且因为配置进了版本控制我能清楚看到每次改了什么、为什么改出问题可以回滚。一个我强烈建议的习惯是每次改完 YAML先跑一次openrig validate做语法和引用检查再跑openrig apply。validate 会检查端点引用是否存在、环境变量是否缺失、端口是否冲突能在应用之前就把大部分低级错误拦下来。这个习惯帮我省了无数次“改完配置工具起不来”的排查时间。还有个小技巧如果你同时用多个模型端点可以在 YAML 里给每个端点加一个health_check字段openrig 启动时会自动探测端点可用性不可用的端点会在日志里标红。这样你一眼就能看出是哪个端点挂了不用逐个 curl 去试。