1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的第一反应是“开放的工具台”。rig 在英文里本意是“装配、装置”在工程圈里常被用来指代一套搭好的工作台或者测试台架。把 open 和 rig 拼在一起字面意思就是“开放式的装配台”。结合热搜词里高频出现的 Claude Code、Codex、YAML、Node.js 这几个关键词我基本能判断出openrig 大概率是一个围绕 AI 编程助手尤其是命令行形态的 Claude Code 和 Codex做统一配置、统一接入、统一管理的开源工具台。为什么我会有这个判断因为最近半年我身边做开发的朋友几乎都在同时用两套甚至三套 AI 编程工具。Claude Code 擅长长上下文推理和复杂重构Codex 系工具在代码补全和快速生成上很顺手再加上本地跑的模型比如通过 LM Studio 挂载的本地推理服务每个人手里其实都攒了一堆配置。问题也随之而来每个工具的配置文件格式不一样Claude Code 用 JSON 加环境变量Codex 用 TOML 或者 YAML本地模型又要单独配 endpoint。时间一长配置文件散落在 home 目录、项目根目录、全局配置目录里改一个参数要翻半天。openrig 要解决的就是这个“配置碎片化”的痛点。它想做的事情我理解下来是用一份统一的 YAML 描述文件把不同 AI 编程工具的接入方式、模型端点、代理规则、环境变量全部收拢到一起然后通过一个 Node.js 写的命令行入口一键把配置分发到各个工具该去的位置。说白了它就是一个“AI 编程工具配置中枢”。这篇文章适合谁看如果你正在用 Claude Code 或者 Codex并且已经厌倦了每次换模型都要手动改三四个文件如果你想在团队里统一大家的 AI 工具配置避免“你那边能跑我这边报错”如果你想把本地模型和云端模型混着用又不想每次都重新配一遍——那 openrig 这套思路值得你花时间研究。下面我会从设计思路、核心细节、实操过程到踩坑排查完整拆一遍。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 为什么选 YAML 作为统一配置层先说配置格式的选择。市面上常见的配置格式无非几种JSON、TOML、YAML、INI。openrig 选 YAML我认为是经过权衡的。JSON 的问题是写起来太啰嗦不能写注释多层嵌套之后括号对齐全靠编辑器。TOML 虽然可读性好但表达嵌套结构时用[table.subtable]这种写法层级一深就容易乱。INI 更不用说只适合扁平配置。YAML 的优势在于支持注释、支持锚点和引用、缩进表达层级直观而且天然适合描述“一份配置分发到多个目标”这种结构。举个实际场景。假设你要同时配置 Claude Code 和 Codex 两个工具它们都要连同一个本地模型端点但各自的字段名不一样。用 YAML 可以这样写profiles: local-dev: endpoint: local_endpoint http://127.0.0.1:1234/v1 api_key: local-key model: qwen2.5-coder targets: claude_code: base_url: *local_endpoint model: claude-sonnet codex: base_url: *local_endpoint model: gpt-5-codex这里的local_endpoint是锚点*local_endpoint是引用。改一处端点两个工具同时生效。这种能力在 JSON 里是没有的在 TOML 里也很难优雅实现。所以 openrig 选 YAML本质上是为了让“一份源配置驱动多个目标”这件事变得自然。提示YAML 对缩进极其敏感Tab 和空格不能混用。我建议统一用两个空格缩进并且在编辑器里开启“显示空白字符”否则一个看不见的 Tab 就能让你排查半小时。2.2 Node.js 作为运行时跨平台与生态的双重考量再说运行时。openrig 用 Node.js 写这个选择我觉得很务实。原因有三点。第一跨平台。Claude Code 和 Codex 的用户分布在 Windows、macOS、Linux 上Node.js 一套代码三端都能跑不需要为每个平台单独编译。第二生态成熟。处理 YAML 有js-yaml处理文件路径有path处理命令行交互有commander和inquirer这些都是现成的轮子不用自己造。第三安装门槛低。用户只要有 Node.js 环境npm install -g openrig就能用不需要额外装 Python 或者编译工具链。这里要特别提醒一句Node.js 版本很关键。热搜词里出现了 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这种报错说明有人踩过版本坑。我的建议是锁定 LTS 版本目前用 Node.js 20.x 或者 22.x 的 LTS 最稳。奇数版本比如 21、23是实验版不要用在生产配置工具上。# 查看当前版本 node -v # 如果版本太老用 nvm 切换到 LTS nvm install --lts nvm use --lts2.3 统一配置分发的核心架构openrig 的架构我拆成三层来理解。最底层是配置源层也就是那份 YAML 文件。它描述了有哪些 profile、每个 profile 连什么端点、用什么模型、走什么代理规则。中间是转换层负责把统一的 YAML 翻译成各个目标工具认识的格式。比如 Claude Code 需要的是环境变量加 JSON 设置文件Codex 需要的是 TOML 配置本地模型可能需要一个 OpenAI 兼容的 endpoint 声明。这一层是 openrig 的核心价值所在也是最容易出问题的地方。最上层是分发层把转换好的配置写到各个工具约定的路径下。比如 Claude Code 的配置通常在~/.claude/目录Codex 的配置在~/.codex/目录。分发层要处理路径不存在时自动创建、已有配置的备份、写入失败的回滚。这个三层架构的好处是新增一个工具支持只需要在转换层加一个适配器源配置和分发逻辑基本不用动。这就是“开放工具台”这个命名的由来——它是一个可以不断挂载新工具的平台。3. 核心细节解析配置文件结构与关键字段3.1 一份完整的 openrig YAML 长什么样我把实际用下来比较顺手的一份配置结构整理出来你可以直接拿去改。这份配置同时管理了 Claude Code、Codex 和本地模型三个目标。version: 1 defaults: timeout: 60 retry: 2 profiles: cloud-main: provider: anthropic base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY model: claude-sonnet-4 local-coder: provider: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: lm-studio model: qwen2.5-coder-14b targets: claude_code: profile: cloud-main settings_path: ~/.claude/settings.json env_prefix: ANTHROPIC codex: profile: local-coder config_path: ~/.codex/config.toml env_prefix: OPENAI active: cloud-main这份配置里有几个关键设计点值得说。version字段是给未来做兼容用的。配置格式一旦要改可以通过版本号做迁移不至于让老用户的配置直接失效。defaults放全局默认值比如超时和重试次数避免每个 profile 重复写。profiles是核心每个 profile 描述一个可用的模型接入点。targets描述每个工具用哪个 profile、配置写到哪、环境变量前缀是什么。最后的active指定当前激活的 profile切换模型只需要改这一个字段。3.2 profile 字段的取舍逻辑profile 里我特意用了api_key_env和api_key两种写法。这不是随意设计的而是有实际考虑的。云端服务的密钥不应该明文写在配置文件里因为配置文件很可能被提交到 Git 仓库。所以云端 profile 用api_key_env只写环境变量的名字真正的密钥放在系统环境变量里。本地模型的密钥通常无所谓因为本地服务一般不校验所以直接写api_key更省事。provider字段决定了转换层怎么处理这个 profile。anthropic和openai-compatible走的是不同的请求格式适配。这里有个坑很多本地推理服务号称“OpenAI 兼容”但实际上在流式响应、工具调用tool use这些高级特性上并不完全兼容。如果你发现 Claude Code 连本地模型时工具调用失效大概率就是兼容性问题不是配置写错了。注意本地模型跑工具调用时对模型的指令遵循能力要求很高。14B 以下的模型经常出现“该调用工具的时候不调用不该调用的时候乱调用”的情况。如果要做复杂的代码重构建议还是用云端大模型。3.3 环境变量前缀的映射规则env_prefix这个字段是很多人第一次用会困惑的地方。它的作用是把 profile 里的通用字段映射成目标工具认识的环境变量名。比如 Claude Code 认的是ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL这几个变量。当env_prefix设为ANTHROPIC时openrig 会自动把 profile 里的base_url、api_key、model拼成对应的变量名。Codex 认的是OPENAI_前缀逻辑一样。这个设计的价值在于源配置里你只写一次base_url不同工具的前缀差异由 openrig 自动处理。新增工具支持时只要知道它的环境变量前缀就能接入。目标工具环境变量前缀配置文件路径配置格式Claude CodeANTHROPIC~/.claude/settings.jsonJSONCodexOPENAI~/.codex/config.tomlTOML通用 OpenAI 兼容OPENAI自定义环境变量3.4 配置合并与优先级实际使用中配置来源往往不止一处全局配置、项目级配置、命令行参数。openrig 的合并优先级我建议按这个顺序命令行参数 项目级配置 全局配置 defaults。为什么项目级要高于全局因为不同项目可能用不同的模型。比如你有个项目专门做前端想用擅长 UI 代码的模型另一个项目做后端想用擅长逻辑推理的模型。项目级配置放在项目根目录的.openrig.yaml里进项目自动生效不用手动切。合并的时候要注意数组字段是覆盖还是追加我的经验是像retry这种标量直接覆盖像headers这种映射做浅合并。这个规则要在文档里写清楚否则用户会困惑为什么自己加的 header 没生效。4. 实操过程从零搭起一套可用的 openrig 环境4.1 环境准备与 Node.js 安装避坑第一步是装 Node.js。这一步看似简单但热搜词里一堆安装报错说明坑不少。Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包一路下一步就行。安装完成后打开 PowerShell输入node -v和npm -v能输出版本号就说明成功了。如果提示“不是内部或外部命令”说明环境变量没配好重新装一遍并勾选“Add to PATH”。macOS 用户我强烈建议用 nvm 管理版本不要用官网的 pkg 安装包。因为 pkg 装完之后想换版本很麻烦而 nvm 一行命令就能切。# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.zshrc # 安装并使用 LTS nvm install --lts nvm use --ltsLinux 用户Ubuntu 为例可以用 apt但 apt 源里的版本通常偏老。我建议同样用 nvm或者用 NodeSource 的源。# 用 NodeSource 装 Node.js 20 LTS curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完之后验证一下node -v # 应该输出 v20.x.x 或 v22.x.x npm -v # 应该输出 10.x.x 以上提示如果你看到 “node.js v24.21.0 is not yet released” 这类报错说明你在尝试安装一个还不存在的版本。去 Node.js 官网确认当前真实的 LTS 版本号别照着博客里的旧版本号抄。4.2 安装 openrig 与初始化配置Node.js 就绪后安装 openrig 本身。如果是全局安装npm install -g openrig如果只是想在某项目里用不污染全局npm install --save-dev openrig npx openrig initinit命令会做几件事在当前目录生成一份.openrig.yaml模板检测系统里已经装了哪些 AI 编程工具然后给出对应的配置建议。我第一次跑的时候它检测到我装了 Claude Code就自动在模板里填好了settings_path。初始化完成后用编辑器打开.openrig.yaml把profiles里的端点、密钥、模型名改成你自己的。改完执行openrig validate这个命令会校验 YAML 语法、检查必填字段、验证端点是否可达。校验通过再执行分发openrig applyapply会把配置写到各个目标工具的位置。执行前它会自动备份已有配置备份文件带时间戳出问题可以回滚。4.3 接入 Claude Code 的完整流程Claude Code 的接入我单独拎出来说因为它是目前用得最多的目标。首先确认 Claude Code 已经装好。安装方式按官方文档来装完后claude --version能输出版本号即可。然后在 openrig 配置里把claude_code这个 target 配好targets: claude_code: profile: cloud-main settings_path: ~/.claude/settings.json env_prefix: ANTHROPIC extra_env: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1extra_env是我加的扩展字段用来塞一些工具特有的环境变量。比如上面这个变量可以关掉一些非必要的网络请求在受限网络环境下能减少报错。执行openrig apply后去~/.claude/settings.json看看内容是不是被正确写入了。然后重启终端让环境变量生效。再跑claude命令如果能看到模型正常响应说明接入成功。这里有个常见问题如果你之前手动配过 Claude Codeapply可能会覆盖你的配置。所以第一次用之前先手动备份一份~/.claude/settings.json。openrig 虽然会自动备份但多一层保险总没错。4.4 接入 Codex 与本地模型的注意事项Codex 的接入逻辑类似但配置文件格式是 TOML字段名也不一样。openrig 的转换层会处理这个差异你只需要在 YAML 里配好 profile 和 target。targets: codex: profile: local-coder config_path: ~/.codex/config.toml env_prefix: OPENAI本地模型的接入要额外注意 endpoint 的写法。LM Studio 默认监听http://127.0.0.1:1234/v1Ollama 默认监听http://127.0.0.1:11434/v1。注意结尾的/v1不能少很多“连接失败”的报错都是因为漏了这个路径。还有一个坑本地模型服务必须先启动再执行openrig apply。因为validate阶段会去探测端点如果服务没起来校验会失败。我一般的工作流是先启动 LM Studio 并加载模型确认curl http://127.0.0.1:1234/v1/models能返回模型列表再跑 openrig。# 验证本地端点是否可用 curl -s http://127.0.0.1:1234/v1/models | head -20如果这个命令返回一堆 JSON说明端点正常。如果返回 connection refused检查服务是否启动、端口是否被占用。4.5 多环境切换的实操技巧实际工作中我经常需要在“云端模型”和“本地模型”之间切换。云端模型质量高但按量计费本地模型免费但能力有限。openrig 的active字段让这个切换变得很简单。我通常准备两个 profilecloud-main和local-coder。写复杂逻辑时切到cloud-main做简单的代码补全和格式化时切到local-coder。切换只需要改一行# 切换到本地模型 openrig use local-coder # 切回云端 openrig use cloud-mainuse命令本质上就是改active字段然后重新 apply。我把它做成了一个 shell 别名切换起来更快alias ocopenrig use cloud-main echo 已切到云端 alias olopenrig use local-coder echo 已切到本地这样在终端里敲oc或ol就能秒切。实测下来这个工作流比手动改配置文件效率高太多。5. 常见问题与排查技巧实录5.1 配置写入后工具不生效怎么办这是最高频的问题。配置明明写进去了但工具行为没变化。排查思路按这个顺序走。第一确认环境变量是否真的加载了。环境变量是在 shell 启动时读取的如果你在已经打开的终端里执行apply新写入的环境变量不会自动生效。解决办法是开一个新终端或者手动source一下配置文件。# 检查环境变量是否生效 echo $ANTHROPIC_BASE_URL echo $OPENAI_BASE_URL第二确认工具读的是不是你改的那个配置文件。有些工具会同时读全局配置和项目级配置项目级的优先级更高。如果你改了全局配置但项目里有覆盖那自然不生效。用openrig doctor命令可以打印出当前实际生效的配置来源。第三确认配置文件格式没被破坏。JSON 文件多一个逗号就会解析失败TOML 的引号用错也会报错。用openrig validate能提前发现这类问题。5.2 端点连接失败的排查路径连接失败分几种情况我整理成一张速查表。报错现象可能原因排查方法connection refused服务未启动或端口错误curl测试端点检查端口占用401 unauthorized密钥错误或未加载检查环境变量确认密钥有效404 not found路径缺少 /v1 或拼写错误核对 base_url 完整路径timeout网络不通或超时设置过短增大 timeout检查网络连通性model not supported模型名拼写错误或不存在调 /models 接口列出可用模型我踩过最深的一个坑是本地模型服务监听的地址是127.0.0.1但我在容器里跑 openrig容器内的127.0.0.1指向容器自己不是宿主机。解决办法是把 base_url 改成宿主机的实际 IP或者用host.docker.internalmacOS 和 Windows 的 Docker Desktop 支持。5.3 模型切换后行为异常的定位有时候配置切换成功了但模型行为很奇怪。比如明明切到了本地小模型回答质量却像大模型或者切到云端了响应速度却像本地。这通常是环境变量没刷新导致的。我的排查方法是在工具里问一个只有特定模型才知道的问题或者直接看响应头里的模型标识。更直接的办法是看工具的日志。Claude Code 可以用--debug参数启动会打印出实际请求的端点和模型。还有一种情况是缓存。有些工具会缓存上一次的模型响应或者配置切换后需要重启工具进程。我一般切换 profile 后习惯性重启一下终端虽然麻烦但能避免很多玄学问题。5.4 团队协作中的配置同步问题团队里每个人机器环境不一样配置同步是个大问题。我的做法是把.openrig.yaml提交到项目仓库但把密钥相关的字段抽出来用环境变量引用。profiles: cloud-main: provider: anthropic base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY # 密钥不入库 model: claude-sonnet-4这样仓库里只有配置结构没有敏感信息。每个人在自己机器上设置ANTHROPIC_API_KEY环境变量即可。新人入职时clone 仓库、装 Node.js、装 openrig、设置环境变量、跑openrig apply五步就能把环境搭好。注意.openrig.yaml里绝对不要写明文密钥。哪怕仓库是私有的也难保不会被误分享或者泄露。用环境变量引用是底线。5.5 版本升级与配置迁移openrig 本身会迭代配置格式也可能变。version字段就是为这个准备的。升级 openrig 后先跑openrig migrate看看有没有配置需要迁移。这个命令会对比当前配置版本和目标版本给出迁移建议。我建议在升级前先备份整个配置目录cp -r ~/.openrig ~/.openrig.bak.$(date %Y%m%d)出问题可以快速回滚。实测下来大部分小版本升级不需要迁移只有大版本version 字段变化才需要。6. 我个人的使用体会与几个实用建议用 openrig 这套思路管理 AI 编程工具配置最大的感受是“终于不用记那么多路径和字段名了”。以前换模型要在三四个文件之间来回改现在改一个 YAML 字段就行。尤其是团队协作场景统一配置带来的效率提升非常明显。几个我踩过坑之后总结的建议。第一配置文件一定要纳入版本控制但密钥一定要抽离。第二本地模型和云端模型分开配 profile不要混在一起切换时更清晰。第三每次改完配置先validate再apply能省掉大量排查时间。第四Node.js 版本锁定 LTS别追新实验版的各种兼容问题不值得你花时间。最后分享一个小技巧如果你同时用 Claude Code 和 Codex可以给它们配不同的 profile一个走云端一个走本地。写核心逻辑时用云端跑批量格式化或者生成测试用例时切本地成本和质量都能兼顾。这个组合我用下来很顺手你可以试试。