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/v1，DeepSeek 的兼容端点又是另一个地址，这些差异应该在 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_KEY="lm-studio"LM Studio 本地服务通常不校验密钥，随便填一个占位符就行，但有些客户端要求这个字段非空，所以还是给个值比较稳。
提示：如果你用
.env文件管理密钥，记得把它加进.gitignore，别不小心提交到仓库里。我见过不止一次有人把密钥推到公开仓库，结果被扫到之后产生意外费用。
3.3 工具配置路径的映射逻辑
Claude Code 和 Codex 各自有自己期望的配置文件位置和格式。Claude Code 一般读~/.claude/settings.json，Codex 读~/.codex/config.toml。openrig 要做的事情，就是根据 YAML 里的定义，生成或更新这些文件。
这里有个细节值得注意：Claude Code 的配置是 JSON，Codex 的是 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 20：
source ~/.bashrc nvm install 20 nvm alias default 20验证一下：
node -v npm -v两个命令都能输出版本号就说明环境没问题了。如果node -v报 command not found，多半是 nvm 的环境变量没加载，检查一下~/.bashrc里有没有 nvm 的初始化脚本。
4.2 安装 Claude Code 与 Codex
Claude 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 配一个简短的别名，启动的时候用别名指定，比记完整的端点地址和模型名要轻松得多。这个习惯我用了大半年，切换效率提升很明显。
