1. 从 openrig 说起一个被名字耽误的本地 AI 编码环境编排器第一次看到openrig这个词我下意识以为是某个硬件测试台架的项目——rig 在工程圈里常指“台架、装置”open 又暗示开源。结果翻了一圈社区讨论和仓库结构才反应过来这玩意儿跟硬件没半点关系它解决的是一个特别具体的痛点把 Claude Code、Codex 这类命令行 AI 编码工具和本地模型、第三方 API、YAML 配置、Node.js 运行时这一堆东西编排成一个可复用、可切换、可版本管理的开发环境。说白了openrig干的事情类似于给 AI 编码工具搭一个“配电箱”。你家里电器多了不可能每台都单独拉一根线到电表得有个配电箱统一管理。Claude Code 要连本地 LM StudioCodex 要接 DeepSeek明天你又想换成 Qwen 或者 GLM如果每次都手动改环境变量、改配置文件、重启终端那效率低得让人抓狂。openrig的思路就是把这些连接关系、模型参数、工具链版本全部写进 YAML用一个统一的入口去加载和切换。这个项目适合谁三类人最需要它。第一类是同时用多个 AI 编码工具的开发者比如白天用 Claude Code 写业务代码晚上用 Codex 跑实验脚本两边模型配置完全不同。第二类是喜欢折腾本地模型的玩家手里有 LM Studio 或者 Ollama想让 Claude Code 调用本地模型而不是走云端。第三类是团队里负责统一开发环境的人需要把一套配置固化下来让新同事 clone 下来就能跑而不是花半天装 Node.js、配 YAML、调 API 地址。我实测下来openrig的核心价值不在于它自己有多复杂而在于它把那些散落在各处的配置碎片——Node.js 版本、YAML 文件路径、API endpoint、模型名称、代理设置——收拢到一个地方。你不需要记住 Claude Code 的配置文件在~/.claude/settings.json还是~/.config/claude/也不需要知道 Codex 的config.toml到底该放哪。openrig用一层抽象把这些差异抹平了。提示如果你只是偶尔用一下 Claude Code没有多模型切换需求那openrig可能有点重。但只要你开始同时维护两套以上的 AI 编码配置它省下的时间会非常可观。2. 核心设计思路拆解为什么是 YAML Node.js 这套组合2.1 为什么选 YAML 而不是 JSON 或 TOMLopenrig把配置层放在 YAML 上这个选择很值得聊。JSON 的问题是不能写注释你没法在配置里标注“这行是给 DeepSeek 用的别删”。TOML 虽然支持注释但嵌套结构一深写起来就变得很啰嗦尤其是当你要描述多个模型、多个 endpoint、多个工具链版本的时候TOML 的[section.subsection.subsubsection]会让人眼花。YAML 的优势在于层级直观、支持注释、支持锚点和引用。举个例子你有三个模型配置它们共享同一个 API base URL只是模型名不同。用 YAML 的锚点可以这样写defaults: defaults api_base: http://localhost:1234/v1 timeout: 30 max_retries: 3 models: local_qwen: : *defaults model_name: qwen2.5-coder-7b local_deepseek: : *defaults model_name: deepseek-coder-v2这种复用能力在 JSON 里要靠工具生成在 TOML 里要靠重复写。YAML 原生支持改一处就全改。openrig正是利用了这个特性把公共配置抽出来让每个模型的差异化配置尽量短。但 YAML 也有坑最大的坑就是缩进敏感。我见过太多人因为 tab 和空格混用导致解析失败报错信息还特别模糊只告诉你“mapping values are not allowed here”根本不告诉你哪一行出了问题。openrig在加载 YAML 的时候做了一层校验会尽量给出更友好的错误提示但你自己写的时候还是得注意统一用两个空格缩进绝对不要用 tab。2.2 Node.js 在这里扮演什么角色很多人看到 Node.js 就头大觉得“我只是想用个 AI 编码工具为什么还要装 Node.js”。这个问题在 Claude Code 和 Codex 的安装教程里被问烂了。答案很简单这两个工具本身就是用 Node.js 写的它们的 CLI 入口是 JavaScript 文件靠 Node 运行时执行。openrig依赖 Node.js 还有一层原因它需要动态生成配置文件。Claude Code 读的是 JSONCodex 读的是 TOML而openrig的源配置是 YAML。中间需要一个转换层Node.js 的js-yaml和toml包正好干这个事。你改 YAMLopenrig在启动时把它转成对应工具认识的格式写到正确的位置然后拉起进程。Node.js 版本的选择也有讲究。Claude Code 官方要求 Node 18 以上Codex 要求 Node 20 以上。如果你系统里只有一个 Node 16两个都跑不起来。openrig的做法是在项目级别锁定 Node 版本通过.nvmrc或者package.json的engines字段声明配合 nvm 或者 fnm 自动切换。这样你全局 Node 版本再乱进到openrig目录里自动切到正确版本。注意如果你在 Windows 上用 nvm-windows它和 Unix 上的 nvm 行为不完全一样.nvmrc不会自动生效需要手动nvm use。这是很多人踩过的坑。2.3 编排层与执行层的分离openrig的架构可以分成两层编排层和执行层。编排层负责读 YAML、解析配置、生成目标工具的配置文件、设置环境变量。执行层就是 Claude Code 或 Codex 本身的进程。这种分离的好处是编排层可以独立测试。你可以先跑openrig dry-run看看它生成的配置文件长什么样确认无误再真正启动工具。我强烈建议第一次配置的时候一定要用 dry-run因为 Claude Code 和 Codex 的配置格式差异很大直接启动如果配错了报错信息往往指向不明。另一个好处是切换成本极低。你想从 Claude Code 切到 Codex不需要重新配置任何东西只需要在 YAML 里改一个active_tool字段或者用命令行参数指定。openrig会重新生成对应工具的配置然后启动。整个过程你不需要碰任何工具原生的配置文件。3. 核心细节解析YAML 配置文件的完整结构与参数含义3.1 顶层结构设计一个典型的openrigYAML 配置文件长这样version: 1.0 runtime: node_version: 20.11.0 package_manager: pnpm tools: claude_code: enabled: true config_path: ~/.claude/settings.json env: ANTHROPIC_BASE_URL: ${models.active.api_base} ANTHROPIC_API_KEY: ${secrets.anthropic_key} codex: enabled: true config_path: ~/.codex/config.toml env: OPENAI_BASE_URL: ${models.active.api_base} OPENAI_API_KEY: ${secrets.openai_key} models: active: local_qwen local_qwen: api_base: http://localhost:1234/v1 model_name: qwen2.5-coder-7b timeout: 60 max_retries: 3 remote_deepseek: api_base: https://api.deepseek.com/v1 model_name: deepseek-coder timeout: 120 max_retries: 2 secrets: anthropic_key: ${env:ANTHROPIC_API_KEY} openai_key: ${env:OPENAI_API_KEY}这个结构里runtime管 Node 版本和包管理器tools管每个 AI 编码工具的配置路径和环境变量models管模型连接信息secrets管密钥引用。关键设计是models.active这个字段它指向当前激活的模型配置其他所有引用都通过${models.active.xxx}动态解析。这种设计的精妙之处在于切换模型只需要改一行。你把active从local_qwen改成remote_deepseek所有工具的 endpoint 和模型名自动跟着变。不需要去 Claude Code 的配置文件里改一遍再去 Codex 的配置文件里改一遍。3.2 环境变量插值的实现细节${}这种插值语法看起来简单实现起来有几个坑。首先是解析顺序openrig需要先解析secrets因为tools里引用了secrets然后解析models因为tools也引用了models最后解析tools。如果顺序错了就会遇到“变量未定义”的错误。其次是循环引用检测。如果有人写了a: ${b}和b: ${a}解析器会陷入死循环。openrig在解析时会维护一个已解析变量的集合遇到重复就报错。这个细节在文档里通常不会写但你如果自己改配置改出循环引用了报错信息会告诉你哪个变量形成了环。第三个坑是环境变量与配置文件变量的优先级。${env:ANTHROPIC_API_KEY}表示从系统环境变量读取${secrets.anthropic_key}表示从配置文件的secrets段读取。如果两者同时存在openrig的默认行为是配置文件优先但可以通过--env-override参数反转。这个设计是为了让 CI/CD 环境可以用环境变量覆盖本地配置而不需要改文件。提示密钥千万不要直接写在 YAML 里。用${env:XXX}引用系统环境变量或者用.env文件配合dotenv加载。YAML 文件如果提交到 git密钥就泄露了。3.3 工具配置路径的跨平台处理Claude Code 在 macOS/Linux 上的配置路径是~/.claude/settings.json在 Windows 上是%USERPROFILE%\.claude\settings.json。Codex 类似但目录名是.codex。openrig需要处理这些差异否则你在 Windows 上写的配置拿到 Linux 上就跑不了。处理方式是用~表示用户主目录由openrig在运行时展开。Node.js 的os.homedir()在三个平台上都能正确返回用户主目录。路径分隔符统一用/Node.js 的path模块会自动处理 Windows 的反斜杠转换。但有一个例外如果配置路径里包含空格比如 Windows 用户名是 “John Doe”那C:\Users\John Doe\.claude\这个路径在传给某些命令行工具时会被截断。openrig在生成配置和启动进程时会对路径做引号包裹但如果你自己写脚本调用记得手动加引号。4. 实操过程从零搭建 openrig 环境的完整步骤4.1 环境准备与 Node.js 安装第一步永远是 Node.js。我推荐用fnm而不是 nvm因为 fnm 是 Rust 写的启动速度快很多而且 Windows 支持更好。安装 fnm 之后装 Node 20 LTS# macOS/Linux 安装 fnm curl -fsSL https://fnm.vercel.app/install | bash # 安装 Node 20 fnm install 20 fnm use 20 node -v # 应该输出 v20.x.xWindows 用户可以用 winget 或者 scoopwinget install Schniz.fnm fnm install 20 fnm use 20装完 Node 之后确认 npm 也能用。openrig本身可以通过 npm 全局安装也可以 clone 仓库本地运行。我建议本地运行因为你需要改 YAML 配置全局安装的话配置文件位置不好找。git clone https://github.com/your-org/openrig.git cd openrig npm installnpm install会装几个关键依赖js-yaml解析 YAMLtoml生成 Codex 配置dotenv加载.env文件commander处理命令行参数。装完之后跑npm link就可以在任意目录用openrig命令了。注意如果你在安装 Node.js 时遇到 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这种报错说明你指定的版本号不存在。Node.js 的版本号是偶数开头为 LTS奇数开头为 Current。24 还没发布用 20 或者 22。4.2 YAML 配置文件的编写与校验环境准备好之后复制示例配置cp openrig.example.yaml openrig.yaml然后编辑openrig.yaml。第一次配置建议只启用一个工具、一个模型跑通之后再扩展。比如先只配 Claude Code 本地 LM Studioversion: 1.0 runtime: node_version: 20.11.0 tools: claude_code: enabled: true config_path: ~/.claude/settings.json env: ANTHROPIC_BASE_URL: http://localhost:1234/v1 ANTHROPIC_API_KEY: lm-studio models: active: local local: api_base: http://localhost:1234/v1 model_name: qwen2.5-coder-7b timeout: 60这里ANTHROPIC_API_KEY填lm-studio是因为 LM Studio 不校验密钥但 Claude Code 要求这个环境变量必须存在随便填一个非空值就行。写完配置后一定要先校验openrig validate这个命令会做几件事检查 YAML 语法是否正确检查必填字段是否缺失检查引用的变量是否存在检查配置路径是否可写。如果一切正常输出 “Configuration valid”。如果有问题会指出具体哪一行哪个字段。我踩过的一个坑是YAML 里用了 tab 缩进validate报错说 “found character \t that cannot start any token”。这个报错还算友好但如果你用的是某些编辑器自动把 tab 转成空格可能看不出来。建议在编辑器里开启“显示空白字符”确保缩进全是空格。4.3 启动 Claude Code 并验证连接校验通过后启动openrig start claude_codeopenrig会做以下动作读取 YAML解析变量生成~/.claude/settings.json设置环境变量然后 exec Claude Code 的入口脚本。你会看到 Claude Code 的交互界面出现。验证是否连上了本地模型最简单的方法是问一个只有本地模型才知道的问题比如“你是什么模型”。如果返回的是 Qwen 或者 DeepSeek 的标识说明连接成功。如果返回的是 Claude 的标识说明配置没生效Claude Code 还在走默认的云端 endpoint。另一个验证方法是看 LM Studio 的日志。LM Studio 在收到请求时会打印日志如果 Claude Code 的请求打到了 LM Studio日志里会有记录。如果日志是空的说明请求根本没发到本地。提示Claude Code 有时候会缓存配置改了settings.json之后需要重启才生效。openrig在启动前会强制覆盖配置文件但如果你手动改了配置又没通过openrig启动可能会遇到缓存问题。4.4 切换到 Codex 并接入 DeepSeekClaude Code 跑通之后加 Codex 就简单了。在 YAML 里加一段tools: codex: enabled: true config_path: ~/.codex/config.toml env: OPENAI_BASE_URL: ${models.active.api_base} OPENAI_API_KEY: ${secrets.deepseek_key} secrets: deepseek_key: ${env:DEEPSEEK_API_KEY}然后在系统里设置DEEPSEEK_API_KEY环境变量。启动 Codexopenrig start codexopenrig会生成~/.codex/config.toml内容大致是[model] provider openai name deepseek-coder [provider.openai] base_url https://api.deepseek.com/v1 api_key sk-xxxxxCodex 的配置格式和 Claude Code 完全不同但openrig帮你屏蔽了这些差异。你只需要在 YAML 里描述“我要用什么模型、endpoint 是什么”剩下的转换由openrig处理。5. 常见问题与排查技巧实录5.1 连接失败类问题速查现象可能原因排查方法Claude Code 启动后无响应endpoint 地址错误用curl手动请求 endpoint 看是否通报错 “organization has disabled claude subscription access”走了云端认证而非本地检查ANTHROPIC_BASE_URL是否被覆盖Codex 报 “model is not supported”模型名拼写错误对照 LM Studio 或 API 提供商的模型列表请求超时timeout 设置太短本地模型首次加载慢调到 120 秒以上401 错误API key 无效检查环境变量是否设置echo $DEEPSEEK_API_KEY这个表里最常遇到的是第一行和第三行。Claude Code 无响应很多时候不是配置问题而是 LM Studio 的模型还没加载完。LM Studio 加载一个 7B 模型大概需要 10-30 秒如果 Claude Code 在这期间发请求就会超时。解决办法是先在 LM Studio 里手动加载模型确认能对话了再启动 Claude Code。5.2 YAML 解析错误的典型场景YAML 报错信息有时候很让人抓狂。我整理了几个最常见的场景一冒号后面没空格。api_base:http://localhost会报错必须是api_base: http://localhost。冒号后面必须有一个空格这是 YAML 的语法要求。场景二字符串里有特殊字符没加引号。比如model_name: qwen:2.5会报错因为冒号被解析成键值分隔符。必须写成model_name: qwen:2.5。场景三多行字符串缩进不对。如果你用|写多行字符串后续行的缩进必须比|所在行多至少一个空格。少一个空格就会解析失败。场景四布尔值歧义。YAML 里yes、no、on、off都会被解析成布尔值。如果你想把它们当字符串用必须加引号。比如model_name: no而不是model_name: no。提示写完 YAML 之后可以用在线的 YAML 校验工具先过一遍比直接跑openrig validate更快定位语法错误。5.3 Node.js 版本冲突的处理如果你系统里已经有一个 Node 版本openrig又要求另一个版本可能会冲突。表现是openrig start时报错 “The engine node is incompatible with this module”。解决办法是用 fnm 或 nvm 切换到正确版本。openrig在启动时会检查runtime.node_version和当前node -v是否匹配不匹配会给出明确提示。如果你用 fnm可以在项目目录放一个.node-version文件内容就是版本号fnm 进入目录时自动切换。另一个坑是全局安装的 npm 包和当前 Node 版本不匹配。比如你用 Node 18 全局装了openrig然后切到 Node 20openrig可能跑不起来。解决办法是不要全局安装用npx或者本地npm link。5.4 代理与网络问题的排查有些第三方 API 在国内访问不稳定需要走代理。openrig支持在 YAML 里配置代理network: proxy: http: http://127.0.0.1:7890 https: http://127.0.0.1:7890 no_proxy: localhost,127.0.0.1no_proxy很重要因为本地 LM Studio 的请求不应该走代理。如果本地请求走了代理会出现“连接被拒绝”或者“超时”的错误。openrig在设置环境变量时会同时设置HTTP_PROXY、HTTPS_PROXY和NO_PROXY确保本地请求直连。排查代理问题时可以用curl -v看请求到底走了哪条路。如果curl直连能通但openrig启动的工具不通大概率是代理环境变量没设置对。6. 进阶玩法多环境配置与团队协作6.1 用 profile 管理多套配置openrig支持 profile 机制你可以在一个 YAML 文件里定义多套配置用--profile参数切换profiles: local: models: active: local_qwen remote: models: active: remote_deepseek team: models: active: team_gateway启动时指定 profileopenrig start claude_code --profile remote这个功能在同一台机器上服务多个项目时特别有用。比如 A 项目要求用本地模型保证代码不出内网B 项目可以用云端模型追求效果。你不需要维护两份 YAML只需要在同一个文件里定义两个 profile。6.2 团队共享配置的注意事项团队协作场景下YAML 文件应该提交到 git但密钥绝对不能提交。做法是把密钥部分抽到.env文件.env加入.gitignore然后提供一个.env.example作为模板# .env.example ANTHROPIC_API_KEYyour_key_here DEEPSEEK_API_KEYyour_key_here新同事 clone 之后复制.env.example为.env填入自己的密钥然后openrig validate确认配置完整。这样既保证了配置的一致性又避免了密钥泄露。另一个团队协作的坑是配置路径的差异。macOS 和 Linux 的路径基本一致但 Windows 的路径分隔符和主目录位置不同。openrig用~和/统一处理但如果你在 YAML 里写了绝对路径比如/Users/john/.claude/那在别人的机器上就跑不了。永远用~开头不要写绝对路径。6.3 与 VS Code 的集成Claude Code 和 Codex 都有 VS Code 扩展openrig生成的配置对扩展同样生效因为扩展底层调用的还是同一个 CLI。但有一个细节VS Code 扩展可能不会读取你 shell 里的环境变量它有自己的环境变量加载机制。解决办法是在 VS Code 的settings.json里显式指定{ claude-code.environment: { ANTHROPIC_BASE_URL: http://localhost:1234/v1, ANTHROPIC_API_KEY: lm-studio } }或者用openrig生成一个 VS Code 的 workspace 配置把环境变量写进去。openrig有一个--vscode参数会在当前目录生成.vscode/settings.json包含所有必要的环境变量。提示VS Code 扩展和 CLI 的配置有时候会打架。如果你在 CLI 里跑通了但扩展不行先检查扩展的设置里有没有覆盖环境变量。7. 我踩过的坑与实操心得第一个坑是YAML 锚点引用在跨文件时失效。openrig支持!include语法引入其他 YAML 文件但锚点不能跨文件引用。如果你在models.yaml里定义了锚点在tools.yaml里用*anchor引用会报错。解决办法是把锚点定义和引用放在同一个文件里或者用openrig的变量插值代替锚点。第二个坑是Claude Code 的配置缓存。Claude Code 启动后会把配置读进内存如果你在运行期间改了settings.json不重启不会生效。openrig在每次start时都会重新生成配置但如果你手动改了配置又没通过openrig启动就会遇到“改了没效果”的情况。我的习惯是永远通过openrig启动不直接跑claude命令。第三个坑是本地模型的上下文长度限制。Claude Code 默认假设模型有 200K 上下文但本地跑的 7B 模型通常只有 8K 或 32K。当对话变长时Claude Code 会把整个历史发给模型超出上下文限制就会报错。解决办法是在 YAML 里设置max_context_tokensopenrig会把这个值传给 Claude Code让它提前截断历史。models: local_qwen: api_base: http://localhost:1234/v1 model_name: qwen2.5-coder-7b max_context_tokens: 8192这个参数在官方文档里不太显眼但没有它长对话基本没法用。第四个坑是Codex 的 TOML 配置里数组和表的区别。Codex 的某些配置项要求是数组比如[model.providers]下面可以定义多个 provider。如果你写成了表而不是数组Codex 会静默忽略不报错但也不生效。openrig在生成 TOML 时会根据 schema 校验类型但如果你手动改生成的 TOML就容易踩这个坑。最后分享一个提高效率的小技巧用openrig env命令导出当前环境变量。这个命令会打印出所有openrig设置的环境变量你可以source它然后在当前 shell 里直接跑claude或codex不需要每次都通过openrig start。这在调试的时候特别方便因为你可以看到工具实际拿到的环境变量是什么。eval $(openrig env --profile local) claude # 直接跑环境变量已经设置好了这个用法在排查“为什么 openrig 能跑但直接跑不行”这类问题时非常有用。