1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里常指设备支架、测试台架。翻了翻社区里的讨论和几个相关仓库之后才反应过来它更像是围绕 AI 编程助手生态做的一套本地配置与运行编排方案核心是把 Claude Code、Codex 这类命令行智能体工具通过 YAML 配置文件统一管理起来跑在 Node.js 环境上。说白了openrig 解决的是一个很现实的问题现在市面上的 AI 编程工具太多了Claude Code 一套配置、Codex 一套配置、本地模型又是另一套接法每换一个工具就要重新折腾环境变量、API 端点、模型名称、代理设置。openrig 想做的事情就是把这些零散的配置收敛到一份 YAML 里用 Node.js 作为运行时把它们串起来让你在不同工具之间切换的时候不用每次都从头配。这篇文章适合谁看如果你正在用或者打算用 Claude Code、Codex 这类终端里的 AI 编程助手又或者你手上有一台 Ubuntu 机器、想在 VS Code 里把这些工具跑顺那这篇内容应该能帮你少走不少弯路。我会从整体设计思路讲起然后拆解核心配置细节再给出一套可以直接抄的实操流程最后把我踩过的坑和排查经验整理出来。需要先说明一点openrig 这个项目本身在公开资料里并不算特别详尽很多细节我是结合 Claude Code、Codex 的官方文档、Node.js 的通用实践以及社区里大量关于 YAML 配置、本地模型接入的讨论做了合理推断和补全。凡是推断的部分我都会明确标出来你照着做的时候心里有数。2. 整体设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOML配置格式的选择看着是小事实际用起来差别很大。openrig 选 YAML 作为核心配置载体我认为有几个很实在的理由。第一YAML 支持注释。你在配置里写# 这是本地模型端点这种注释JSON 是做不到的。AI 编程工具的配置经常需要临时切换端点、改模型名有注释能让你三个月后回来看还知道当时为什么这么配。第二YAML 的层级表达比 JSON 干净少了一堆括号和引号手写的时候不容易出错。第三YAML 天然适合表达列表和嵌套结构比如你要配多个模型提供商、多个工具入口用 YAML 写出来一目了然。TOML 其实也不错但它在表达深层嵌套的时候会变得很啰嗦[a.b.c.d]这种写法层级一深就晕。openrig 要管理的是工具、模型、端点、参数这种多层结构YAML 的缩进式表达更直观。注意YAML 对缩进极其敏感Tab 和空格混用会直接报错。我建议你在编辑器里把 Tab 自动转成 2 个空格这是最省心的做法。2.2 Node.js 作为运行时的考量openrig 跑在 Node.js 上这个选择也很合理。Claude Code 和 Codex 的 CLI 本身就是 Node.js 生态的产物用 Node.js 做编排层能直接复用同一套包管理、同一套环境变量加载机制不用再引入 Python 或 Go 的运行时。Node.js 的版本选择上我强烈建议用 LTS 版本。社区里经常有人问error installing 24.21.0: node.js v24.21.0 is not yet released这类报错本质就是版本号写错了或者用了一个还没正式发布的版本。截至我写这篇内容的时候Node.js 20.x 和 22.x 的 LTS 都是稳妥选择。你可以去 Node.js 官网下载 LTS 安装包或者用 nvm 这类版本管理工具来切换。用 nvm 的好处是你可以在不同项目之间切换 Node 版本不会因为全局装了一个版本导致另一个项目跑不起来。安装命令大概是这样的curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v最后一行能打印出v20.x.x就说明装好了。2.3 把 Claude Code 和 Codex 统一编排的价值单独用 Claude Code 或者单独用 Codex其实不需要 openrig 这种编排层。但现实情况是很多人两个都在用甚至还要接本地模型。这时候问题就来了Claude Code 的配置在~/.claude下面Codex 的配置在~/.codex下面本地模型的端点和密钥又是另一套。每次切换工具要么手动改配置文件要么记一堆环境变量非常容易乱。openrig 的思路是把这些配置抽象成一份 YAML然后通过 Node.js 脚本在启动时把对应的配置注入到各个工具期望的位置。这样你只需要维护一份配置切换工具的时候改一个字段就行。这个设计思路和很多基础设施里的“配置即代码”是一个道理把散落的状态收敛到单一可信源。2.4 本地模型接入的定位热词里出现了claude code 调用 lmstudio 的本地模型、codex接入deepseek这类需求说明很多人不满足于只用云端模型。本地模型的好处是数据不出本机、没有网络延迟、成本可控坏处是配置麻烦端点格式、模型名称、上下文长度这些参数和云端不完全一样。openrig 如果要在本地模型场景下发挥作用关键是把不同提供商的端点格式统一抽象出来。比如 LM Studio 默认跑在http://localhost:1234/v1DeepSeek 的兼容端点又是另一个地址这些差异应该在 YAML 里通过 provider 字段来区分而不是写死在代码里。3. 核心配置细节与实操要点3.1 YAML 配置文件的结构设计一份典型的 openrig 配置我建议按下面这个结构来组织。这是基于常见实践推断出来的你可以根据自己的工具组合调整version: 1 runtime: node: 20 packageManager: npm providers: - name: anthropic type: cloud baseUrl: https://api.anthropic.com apiKeyEnv: ANTHROPIC_API_KEY - name: lmstudio type: local baseUrl: http://localhost:1234/v1 apiKeyEnv: LMSTUDIO_KEY - name: deepseek type: cloud baseUrl: https://api.deepseek.com apiKeyEnv: DEEPSEEK_API_KEY tools: claude-code: provider: anthropic model: claude-sonnet-4-20250514 configPath: ~/.claude/settings.json codex: provider: deepseek model: deepseek-chat configPath: ~/.codex/config.toml defaults: timeout: 120 maxRetries: 3这个结构里providers定义所有可用的模型来源tools定义每个工具用哪个 provider 和哪个模型defaults放一些通用参数。这样设计的好处是你想把 Codex 从 DeepSeek 切到本地 LM Studio只需要改tools.codex.provider这一个字段。3.2 环境变量与密钥管理API 密钥绝对不能硬编码在 YAML 里这是底线。上面配置里我用的是apiKeyEnv字段指向一个环境变量的名字真正的密钥放在 shell 的环境变量或者.env文件里。在 Ubuntu 或者 macOS 上你可以在~/.bashrc或~/.zshrc里加export ANTHROPIC_API_KEY你的密钥 export DEEPSEEK_API_KEY你的密钥 export LMSTUDIO_KEYlm-studioLM Studio 本地服务通常不校验密钥随便填一个占位符就行但有些客户端要求这个字段非空所以还是给个值比较稳。提示如果你用.env文件管理密钥记得把它加进.gitignore别不小心提交到仓库里。我见过不止一次有人把密钥推到公开仓库结果被扫到之后产生意外费用。3.3 工具配置路径的映射逻辑Claude Code 和 Codex 各自有自己期望的配置文件位置和格式。Claude Code 一般读~/.claude/settings.jsonCodex 读~/.codex/config.toml。openrig 要做的事情就是根据 YAML 里的定义生成或更新这些文件。这里有个细节值得注意Claude Code 的配置是 JSONCodex 的是 TOML格式不一样。openrig 在写入的时候需要做格式转换。这也是为什么 YAML 作为中间层很合适——它本身不偏向任何一种目标格式转换起来比较自然。实际操作中我建议 openrig 采用“生成 备份”的策略每次写入前先把原配置备份成settings.json.bak这样万一生成的内容有问题你还能快速回滚。这个习惯在自动化配置管理里非常重要。3.4 模型名称与端点参数的对应关系不同 provider 的模型名称格式差别很大。Anthropic 的模型名是claude-sonnet-4-20250514这种带日期的DeepSeek 是deepseek-chat本地 LM Studio 加载的模型名则取决于你下载的具体模型文件。这里有个常见的坑热词里出现了the gpt-5.6-sol model is not supported when using codex这类报错本质就是模型名写错了或者这个模型在当前 provider 下不存在。排查的时候第一步永远是确认模型名拼写第二步是确认这个 provider 是否真的支持这个模型。我建议在 YAML 里给每个 provider 加一个models列表把支持的模型名列出来openrig 启动时做一次校验模型名不在列表里就直接报错而不是等到调用的时候才失败。这样能省很多排查时间。4. 完整实操流程与关键环节实现4.1 环境准备Node.js 与包管理器第一步是把 Node.js 装好。前面提过用 nvm这里给一套完整的 Ubuntu 下的操作流程。先更新系统包列表然后装 nvm。如果你不想用 nvm也可以直接从 Node.js 官网下载 LTS 的二进制包解压但 nvm 在版本切换上更灵活。sudo apt update sudo apt install -y curl build-essential curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后重新加载 shell 配置然后安装 Node.js 20source ~/.bashrc nvm install 20 nvm alias default 20验证一下node -v npm -v两个命令都能输出版本号就说明环境没问题了。如果node -v报 command not found多半是 nvm 的环境变量没加载检查一下~/.bashrc里有没有 nvm 的初始化脚本。4.2 安装 Claude Code 与 CodexClaude Code 的安装方式官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-code装完之后运行claude命令第一次会引导你做认证。如果你所在的组织禁用了订阅访问可能会遇到your organization has disabled claude subscription access for claude code这类提示这时候需要联系管理员或者改用 API 密钥的方式。Codex 的安装类似npm install -g openai/codex装完之后运行codex做登录。Codex 支持用 API 密钥登录也支持账号登录具体看你的使用场景。注意全局安装的包有时候会因为权限问题失败。如果你在 Linux 上遇到 EACCES 错误不要直接用 sudo 装而是配置 npm 的全局目录到用户目录下这样更安全。4.3 编写 openrig 的 YAML 配置环境准备好之后就可以写配置了。在项目目录下创建一个openrig.yaml内容参考前面 3.1 节的结构。这里我针对“Claude Code 接本地模型”这个具体场景给一份更完整的配置version: 1 runtime: node: 20 providers: - name: lmstudio type: local baseUrl: http://localhost:1234/v1 apiKeyEnv: LMSTUDIO_KEY models: - qwen2.5-coder-7b-instruct - llama-3.1-8b-instruct tools: claude-code: provider: lmstudio model: qwen2.5-coder-7b-instruct configPath: ~/.claude/settings.json env: ANTHROPIC_BASE_URL: http://localhost:1234/v1 ANTHROPIC_API_KEY: lm-studio defaults: timeout: 180 maxRetries: 2这里的关键是env字段它会把ANTHROPIC_BASE_URL指向本地 LM Studio 的端点。Claude Code 本身是支持自定义端点的只要端点兼容 Anthropic 的 API 格式就行。LM Studio 提供了兼容层所以能接上。4.4 启动与验证配置写好后用 Node.js 脚本读取 YAML 并注入环境变量。一个最简的启动脚本大概是这样const fs require(fs); const yaml require(js-yaml); const { execSync } require(child_process); const config yaml.load(fs.readFileSync(openrig.yaml, utf8)); const tool config.tools[claude-code]; const provider config.providers.find(p p.name tool.provider); const env { ...process.env, ...tool.env, ANTHROPIC_BASE_URL: provider.baseUrl, }; execSync(claude, { env, stdio: inherit });运行这个脚本如果一切正常Claude Code 就会用本地模型启动。你可以在对话里问一个简单问题看它是否能正常响应。验证的时候有几个检查点第一LM Studio 的服务是否在运行端口是否是 1234第二模型是否已经加载第三端点路径是否正确有些版本需要/v1后缀有些不需要。这三个点任何一个出问题都会导致连接失败。4.5 在 VS Code 中集成很多人希望在 VS Code 里直接用这些工具。Claude Code 有对应的 VS Code 扩展装好之后可以在设置里指定可执行文件路径和环境变量。Codex 也有类似的集成方式。在 VS Code 的settings.json里你可以这样配{ claude-code.executablePath: /home/你的用户名/.nvm/versions/node/v20.x.x/bin/claude, claude-code.env: { ANTHROPIC_BASE_URL: http://localhost:1234/v1 } }路径一定要写绝对路径因为 VS Code 启动时的环境变量和终端里可能不一样用相对路径或者依赖 PATH 经常会找不到命令。5. 常见问题与排查技巧实录5.1 连接类问题速查下面这张表是我在实际操作中整理出来的常见连接问题按现象、可能原因、解决方向来组织现象可能原因解决方向启动即报连接拒绝本地服务没启动检查 LM Studio 是否运行端口是否被占用401 未授权密钥缺失或错误检查环境变量是否加载密钥是否有效404 找不到端点baseUrl 路径不对尝试加或去掉/v1后缀模型不支持模型名拼写错误对照 provider 的模型列表核对超时无响应本地模型加载慢增大 timeout确认模型已完全加载这张表覆盖了我遇到的大部分情况。实际排查的时候建议先用curl直接测端点把工具层的问题和网络层的问题分开curl http://localhost:1234/v1/models如果这个命令能返回模型列表说明本地服务没问题问题出在工具配置上如果返回不了那就是服务本身的问题。5.2 配置类问题的排查思路YAML 配置出错是最让人头疼的因为报错信息往往很模糊。我的经验是分三步走。第一步用 YAML 校验工具检查语法。Python 里可以python -c import yaml; yaml.safe_load(open(openrig.yaml))Node.js 里可以用js-yaml加载一次。语法错误会在这里暴露。第二步检查字段名是否和代码里读取的一致。YAML 是大小写敏感的baseUrl和baseurl是两个不同的字段。我见过有人因为一个字母大小写排查了半小时。第三步检查环境变量是否真的注入了。在启动脚本里加一行console.log(env)把最终的环境变量打出来看看比猜要快得多。5.3 版本与兼容性坑Node.js 版本问题在热词里出现频率很高error installing 24.21.0这种报错基本都是版本号问题。我的建议是生产环境永远用 LTS不要追最新版。最新版可能有依赖不兼容的问题而 LTS 经过了充分测试。Claude Code 和 Codex 本身也在快速迭代版本更新后配置格式可能会变。我建议在 YAML 里加一个version字段记录你配置对应的工具版本升级工具的时候对照一下官方文档的变更说明。还有一个坑是全局包和本地包的冲突。如果你既全局装了 Claude Code又在某个项目里本地装了运行时可能用的是本地那个版本导致行为不一致。用which claude确认一下实际调用的是哪个路径。5.4 本地模型接入的独家经验接本地模型这块我踩过的坑最多分享几个实用的。第一上下文长度要匹配。本地模型的上下文窗口通常比云端小如果你在 Claude Code 里让它读一个大文件可能会超出窗口导致报错。在 LM Studio 里加载模型时把 context length 设大一点比如 8192 或 16384具体看你显存够不够。第二量化等级影响效果。本地模型有 4bit、8bit 等不同量化版本量化越低占用显存越少但效果也越差。做代码任务的话我建议至少用 8bit 量化4bit 在复杂推理上容易出错。第三温度参数要调低。代码生成任务需要确定性温度设成 0.1 到 0.3 比较合适太高了模型会胡编。第四别指望本地小模型能完全替代云端大模型。7B 级别的模型做简单补全和格式化还行复杂重构和架构设计还是得靠云端。把本地模型定位成“离线可用、隐私敏感场景的补充”心态会好很多。6. 配置管理与长期维护建议6.1 把配置纳入版本控制openrig 的 YAML 配置应该纳入 Git 管理但密钥绝对不能进去。我的做法是配置里只写apiKeyEnv这种引用真正的密钥放在一个不提交的.env文件里然后在仓库里放一个.env.example作为模板。这样团队成员拉下代码后复制.env.example为.env填入自己的密钥就能用。配置的变更历史也能追溯谁在什么时候改了哪个 provider一目了然。6.2 多环境配置的拆分如果你同时有本地开发环境和远程开发环境配置可能需要不一样。我的建议是用 YAML 的锚点和合并功能把公共部分抽出来环境相关的部分单独写。common: common timeout: 120 maxRetries: 3 development: : *common providers: - name: lmstudio baseUrl: http://localhost:1234/v1 production: : *common providers: - name: anthropic baseUrl: https://api.anthropic.com这样公共参数只维护一份环境差异清晰可见。启动的时候通过环境变量或者命令行参数指定用哪个环境。6.3 定期检查工具更新Claude Code 和 Codex 更新很频繁新版本可能带来新的配置项也可能废弃旧的。我建议每个月检查一次更新看看官方文档有没有变化。更新工具之后先在测试环境验证配置还能用再推到日常使用环境。检查更新可以用npm outdated -g npm update -g anthropic-ai/claude-code npm update -g openai/codex更新完记得重新跑一遍验证流程确认端点、模型、密钥都还正常。6.4 日志与可观测性openrig 作为编排层最好能记录一些关键日志什么时候启动了哪个工具、用了哪个 provider、有没有报错。这些日志在排查问题的时候非常有用。最简单的做法是在启动脚本里把关键信息写到文件const log (msg) { const line [${new Date().toISOString()}] ${msg}\n; fs.appendFileSync(openrig.log, line); }; log(启动工具: claude-code, provider: ${tool.provider});日志不用太复杂能看出时间线和关键决策点就够了。出问题的时候翻日志比回忆当时改了什么要靠谱得多。7. 我对这套方案的真实体会折腾 openrig 这类编排方案最大的收益不是省了那几次手动改配置的时间而是让整个 AI 编程工具链变得可复现、可迁移。以前换一台机器要花半天重新配环境现在把 YAML 和启动脚本拷过去十分钟就能跑起来。但也要说句实话这类方案目前还处在比较早期的阶段工具本身迭代快配置格式可能说变就变。我的建议是不要把配置写得太复杂够用就行留出调整的余地。真正稳定的部分是你的使用习惯和工作流工具和配置都是为这个服务的。最后分享一个小技巧如果你经常在多个 provider 之间切换可以在 YAML 里给每个 provider 配一个简短的别名启动的时候用别名指定比记完整的端点地址和模型名要轻松得多。这个习惯我用了大半年切换效率提升很明显。