1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的画面是矿场里的“钻机”——rig 在英文里本来就有钻井平台、机架、装备的意思。把它放到当下 AI 编程工具爆发的语境里这个命名其实非常贴切它想做的就是给一堆散落各处的 AI 编程助手Claude Code、Codex 这类 CLI 工具搭一个统一的“机架”让它们能被规整地挂载、切换、配置和管理。我接触这类工具链的起点和很多人一样是从claude code和codex这两个命令行助手开始的。用久了就会发现一个很现实的问题每个工具都有自己的配置文件、自己的环境变量、自己的模型接入方式。Claude Code 走一套 Anthropic 的订阅或 API 逻辑Codex 走 OpenAI 那一套你想让它们都指向本地模型或者第三方兼容端点就得分别去改各自的配置。时间一长~/.claude、~/.codex、各种config.yaml、settings.json散落一地换台机器或者重装系统光是恢复这套环境就能折腾半天。openrig要处理的正是这个“多工具、多模型、多配置”的混乱局面。它本质上是一个面向 AI 编程 CLI 工具的配置编排层核心载体是 YAML 文件运行依赖 Node.js 生态。你可以把它理解成一个“总控台”用一份结构化的 YAML 描述清楚你要挂载哪些工具、每个工具用哪个模型端点、走什么认证方式然后由 openrig 负责把这些配置分发到各个工具真正读取的位置。这篇文章适合三类人看。第一类是已经在用claude code或codex但被多套配置搞得头大的开发者第二类是刚听说这些工具、想一次性把环境搭明白的新手第三类是想把 AI 编程助手接入本地模型或第三方兼容服务、需要统一管理配置的进阶用户。我会从设计思路讲到 YAML 怎么写、Node.js 环境怎么准备、常见报错怎么排查尽量把踩过的坑都摊开讲。需要先说明一点openrig这个项目本身相对小众公开资料不算多所以文中涉及的具体字段名、目录结构我会基于这类配置编排工具的通用实践来合理推演并明确标注哪些是“常见做法推断”。你在实际使用时以项目仓库里的 README 和示例配置为准。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做配置层而不是 JSON 或 TOML很多人第一反应会问配置文件为什么不用 JSONJSON 不是更通用吗我实际用下来YAML 在这个场景里有几个 JSON 比不了的优势。第一是注释。AI 工具的配置里经常需要标注“这个 key 从哪来的”“这个端点什么时候换的”JSON 不支持注释你只能另开一个文档记时间一长就对不上了。YAML 用#就能写注释配置和说明放在一起维护成本低很多。第二是多行字符串。很多工具的配置里要写系统提示词system prompt或者较长的指令模板YAML 的|和语法处理多行文本非常自然JSON 里你得把换行符转义成\n可读性极差。第三是层级表达。openrig 要描述“工具 → 模型 → 认证 → 参数”这种多层嵌套关系YAML 的缩进式结构读起来比 JSON 的一堆花括号清爽得多。当然缩进也是 YAML 最大的坑这个后面会专门讲。至于为什么不用 TOML主要是 TOML 在表达深层嵌套和数组套对象时比较啰嗦而 openrig 的配置天然是“一个工具列表每个工具下面挂一堆子配置”的结构YAML 更顺手。2.2 Node.js 作为运行时生态与跨平台的权衡openrig 选择 Node.js 作为运行时我认为是权衡后的结果。这类工具需要做几件事读写文件系统、解析 YAML、发起 HTTP 请求、可能还要起一个本地代理进程。Node.js 在这几件事上都有成熟的库js-yaml或yaml负责解析fs-extra负责文件操作内置的http模块或undici负责网络请求。更关键的是跨平台。用 Node.js 写Windows、macOS、Linux 上都能跑不用为每个平台单独编译。而且claude code、codex这些工具本身就是 npm 包用户机器上大概率已经装了 Node.jsopenrig 直接复用这个运行时不需要用户再装 Python 或 Go 环境降低了上手门槛。这里有个细节值得说Node.js 的版本选择很关键。我建议用LTS 版本比如 20.x 或 22.x。网上经常有人搜到error installing 24.21.0: node.js v24.21.0 is not yet released这种报错本质上是版本号写错了或者源里还没有这个版本。装 Node.js 最稳的方式是去官网下载 LTS 安装包或者用nvmNode Version Manager来管理多版本。用 nvm 的好处是你可以在不同项目间切换 Node 版本遇到某个工具只兼容特定版本时不用重装系统级 Node。2.3 配置分发openrig 的核心价值所在openrig 真正有价值的地方不在于它“能读 YAML”而在于它把 YAML 里的抽象配置翻译成各个工具真正认识的格式并写到正确的位置。举个具体例子。假设你在 openrig 的 YAML 里写了这样一段意图“Claude Code 使用本地模型端点Codex 使用另一个兼容端点”。openrig 需要知道Claude Code 读取配置的路径是什么可能是~/.claude/settings.json或环境变量Codex 读取配置的路径是什么可能是~/.codex/config.yaml或config.toml每个工具期望的字段名和格式是什么认证信息怎么传递环境变量、配置文件字段、还是命令行参数这些“翻译规则”就是 openrig 的核心逻辑。它把用户从“记住每个工具的配置细节”中解放出来你只需要在 openrig 层面描述意图剩下的分发工作它来做。这也是为什么它叫“rig”——一个统一的挂载框架。提示配置分发类工具最大的风险是“覆盖用户已有配置”。好的实现应该支持备份、合并或 dry-run 预览。你在第一次运行 openrig 前务必先备份~/.claude、~/.codex这些目录。3. 核心细节解析YAML 配置结构与关键字段3.1 一份典型的 openrig 配置长什么样基于这类工具的通用设计一份 openrig 配置大致会包含三个层级全局设置、工具定义、模型端点定义。我把它拆开讲你可以对照自己的需求调整。# openrig 全局配置示例基于常见实践推断 version: 1 # 全局默认设置被各工具继承 defaults: timeout: 30000 # 请求超时单位毫秒 retry: 2 # 失败重试次数 log_level: info # 日志级别debug/info/warn/error # 模型端点定义可被多个工具复用 endpoints: local-llm: base_url: http://127.0.0.1:1234/v1 api_key: ${LOCAL_LLM_KEY} # 从环境变量读取避免明文 model: local-model-name remote-compat: base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} model: compat-model-v1 # 工具定义每个工具挂载到某个端点 tools: claude-code: enabled: true endpoint: local-llm extra: max_tokens: 8192 codex: enabled: true endpoint: remote-compat extra: reasoning_effort: medium这份配置里endpoints和tools是分离的好处是一个端点可以被多个工具共享。比如你本地跑了一个兼容 OpenAI 协议的服务Claude Code 和 Codex 都想用那只需要定义一次local-llm两个工具都引用它就行。改端点地址时也只改一处。3.2 环境变量插值别把密钥写进文件上面配置里用了${LOCAL_LLM_KEY}这种写法这是 YAML 配置里非常关键的一个技巧。永远不要把 API key 明文写进配置文件原因有两个一是配置文件可能被同步到云盘或提交到 Git密钥泄露风险极高二是不同机器上密钥可能不同写死了就没法复用配置。环境变量插值的实现方式通常是在解析 YAML 后用正则匹配${VAR_NAME}并替换成process.env.VAR_NAME的值。如果变量不存在好的实现应该报错而不是静默替换成空字符串——静默替换会导致认证失败但报错信息里看不出是密钥缺失排查起来很痛苦。设置环境变量的方式Linux/macOS 下在~/.bashrc或~/.zshrc里写export LOCAL_LLM_KEYxxxWindows 下用系统环境变量设置或者 PowerShell 的$env:LOCAL_LLM_KEYxxx。改完记得重新打开终端或source一下配置文件。3.3 YAML 缩进新手最容易翻车的地方我见过太多人第一次写 YAML 就栽在缩进上。YAML 用缩进表示层级关系不允许用 Tab只能用空格而且同一层级的缩进量必须一致。下面这段就是典型的错误tools: claude-code: enabled: true endpoint: local-llm # 错误缩进比上一行少一个空格endpoint这一行缩进是 3 个空格而enabled是 4 个空格YAML 解析器会认为endpoint是claude-code的兄弟节点而不是子节点直接报解析错误。这种错误肉眼很难看出来尤其是从网页复制配置的时候经常混入不可见字符。我的建议是用支持 YAML 语法高亮的编辑器比如 VS Code 装一个 YAML 插件缩进错误会直接标红。另外写完配置后用python -c import yaml; yaml.safe_load(open(config.yaml))或者 Node.js 的js-yaml先验证一遍比直接跑 openrig 再报错要快得多。3.4 工具挂载的字段设计逻辑每个工具下面的字段设计时要考虑“通用性”和“工具特异性”的平衡。通用字段比如enabled、endpoint、timeout所有工具都有但每个工具又有自己的特殊参数比如 Claude Code 可能关心max_tokensCodex 可能关心reasoning_effort。所以配置结构里通常会有一个extra或options字段用来放工具特有的参数。这种设计的逻辑是openrig 只负责它认识的通用字段extra里的内容原样透传给对应工具。这样即使某个工具升级加了新参数openrig 不用改代码你在extra里加上就行。这是一种“开放封闭”的设计思路扩展性好。注意extra里的字段名必须和工具本身期望的完全一致大小写、下划线都不能错。透传意味着 openrig 不做校验写错了工具那边会报错但错误信息可能不会指向 openrig排查时容易绕弯路。4. 实操过程从零把 openrig 环境搭起来4.1 Node.js 环境准备与版本选择第一步是确认 Node.js 环境。打开终端运行node -v npm -v如果提示命令不存在说明还没装。去 Node.js 官网下载 LTS 版本安装包Windows 下是.msimacOS 下是.pkgLinux 下可以用包管理器或者下载二进制包。安装完成后重新打开终端再验证一次。我强烈建议用nvm而不是系统级安装。原因很简单AI 工具链更新快不同工具对 Node 版本要求可能冲突。用 nvm 可以随时切换# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装并使用 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20Windows 用户可以用nvm-windows功能类似。装好后nvm ls能看到已安装的版本列表。这里要提醒一个常见坑网上有些教程会让你装某个具体版本号比如nvm install 24.21.0但如果这个版本还没正式发布就会报node.js v24.21.0 is not yet released or is not available。装 LTS 大版本号就行nvm 会自动选该系列最新的稳定版。4.2 安装 openrig 与初始化配置Node.js 就绪后安装 openrig。如果它发布在 npm 上通常是npm install -g openrig-g表示全局安装这样在任何目录下都能调用openrig命令。安装完成后运行openrig --version确认。接下来初始化配置。大多数这类工具会提供一个init命令生成模板openrig init它会在当前目录或用户配置目录下生成一份openrig.yaml模板。如果没有init命令就手动创建配置文件路径通常在~/.config/openrig/config.yaml或项目根目录。具体路径以项目文档为准。初始化后用编辑器打开配置文件按照第 3 节的示例填入你的端点和工具信息。第一次配置建议只启用一个工具跑通之后再逐步加这样出问题容易定位。4.3 配置本地模型端点以兼容 OpenAI 协议的服务为例很多人用 openrig 的核心诉求是让 Claude Code 或 Codex 接入本地模型。本地模型服务通常暴露一个兼容 OpenAI 协议的 HTTP 端点比如http://127.0.0.1:1234/v1。配置时要注意几个点。第一base_url 的结尾。有的服务要求带/v1有的不带还有的要求带/v1/chat/completions完整路径。这个必须查你所用服务的文档写错了会返回 404。第二model 字段的值。本地服务加载的模型名必须和服务端实际加载的名字一致。有的服务对模型名大小写敏感Llama-3和llama-3可能被当成两个模型。第三api_key 的处理。本地服务很多不校验 key但客户端库可能强制要求非空。这种情况下随便填一个占位符比如sk-local通常就能过。配置好后用 curl 先测一下端点通不通curl http://127.0.0.1:1234/v1/models \ -H Authorization: Bearer sk-local能返回模型列表说明端点没问题再去配 openrig。4.4 把配置分发到 Claude Code 和 Codexopenrig 的核心动作是“分发”。运行类似openrig apply的命令后它会读取 YAML把配置翻译成各工具认识的格式并写入。以 Claude Code 为例它可能读取~/.claude/settings.json或依赖环境变量ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY。openrig 需要把 YAML 里的endpoint信息转换成这些。Codex 类似可能读取~/.codex/config.yaml或config.toml。分发完成后一定要验证。启动 Claude Code随便问一个问题看它是否走的是你配置的端点。如果本地模型服务有日志观察是否有请求进来。这一步能确认配置真的生效了而不是写到了错误的位置。提示如果分发后工具行为没变化先检查工具是否读取了 openrig 写入的那个文件。有些工具支持多个配置来源优先级不同可能你改的文件被更高优先级的配置覆盖了。4.5 用 dry-run 预览分发结果成熟的配置分发工具通常支持--dry-run或--check参数只显示“将要做什么”而不实际写入。第一次配置强烈建议先跑 dry-runopenrig apply --dry-run输出会列出每个工具将要写入的文件路径和内容摘要。你核对无误后再去掉--dry-run真正执行。这个习惯能帮你避免“配置写错把原有环境搞坏”的尴尬。5. 常见问题与排查技巧实录5.1 配置解析类问题速查报错现象可能原因排查方法YAMLException: bad indentation缩进用了 Tab 或空格数不一致用编辑器显示不可见字符统一用 2 或 4 空格Cannot read property xxx of undefined引用了不存在的端点名检查tools里的endpoint值是否在endpoints中定义环境变量替换后为空变量未 export 或拼写错误echo $VAR_NAME确认变量存在duplicate key同一层级出现重复字段名搜索配置里是否有重复的 keyYAML 解析错误是最常见的而且报错信息往往只给行号不给具体原因。我的经验是从报错行往上找最近的缩进变化问题通常出在那里。5.2 端点连接类问题cc switch local proxy failed while handling codex endpoint /responses这类报错本质是代理层在转发请求时失败了。可能的原因有几个端点地址写错、端点服务没启动、认证信息不对、或者请求格式和目标端点不兼容。排查顺序建议是先用 curl 直接打端点确认端点本身可用再检查 openrig 配置里的base_url和api_key最后看 openrig 的日志通常--log-level debug能打出请求详情对比它实际发出的请求和你 curl 的差异。还有一种情况是模型名不被支持比如报the gpt-5.6-sol model is not supported。这说明你配置的模型名端点不认。要么改成端点支持的模型名要么确认端点是否真的加载了这个模型。5.3 工具侧配置不生效配置分发完了但工具行为没变这类问题最让人抓狂。我的排查清单是这样的确认 openrig 写入的文件路径和工具实际读取的路径是否一致检查是否有环境变量覆盖了配置文件环境变量优先级通常更高确认工具是否需要重启才能重新读取配置查看工具自己的日志看它加载的是哪个配置有一次我遇到 Claude Code 一直走默认端点折腾半天发现是 shell 里有个旧的ANTHROPIC_BASE_URL环境变量没清掉优先级高于配置文件。环境变量和配置文件的优先级关系是这类问题的重灾区一定要搞清楚。5.4 订阅与权限相关的提示有时候会看到your organization has disabled claude subscription access for claude code这类提示。这通常和账号的订阅状态或组织策略有关不是 openrig 配置能解决的。遇到这种情况先确认账号本身的访问权限再考虑是不是要走 API 而非订阅的方式接入。5.5 我的几条实操心得第一配置改动前先备份。cp -r ~/.claude ~/.claude.bak这种操作花不了几秒但能救命。第二一次只改一个变量。同时改端点和模型名出问题时你不知道是哪个导致的。改一个、测一个是最笨但最有效的方法。第三日志级别调到 debug。info 级别的日志通常只告诉你“成功了”或“失败了”debug 级别才会打出实际的请求 URL、请求头、响应码这些才是排查的关键。第四善用版本控制。把 openrig 的 YAML 配置纳入 Git 管理密钥用环境变量不进仓库每次改动都有记录出问题能快速回滚。6. 进阶玩法多工具协同与配置复用6.1 一套配置管理多个工具openrig 真正的威力在于你可以在一个 YAML 里管理 Claude Code、Codex 以及未来可能加入的其他工具。当你想切换模型时只改endpoints里的一处所有引用它的工具同时生效。这种“一处修改多处生效”的能力在工具数量多起来之后价值非常明显。我自己的做法是把配置分成两层一层是endpoints.yaml只放端点定义一层是tools.yaml放工具和它们的挂载关系。openrig 如果支持include或配置合并就可以把两层拼起来。这样端点信息可以单独维护甚至在不同项目间复用。6.2 为不同项目准备不同配置如果你同时在做多个项目每个项目想用不同的模型或端点可以准备多份 openrig 配置通过--config参数指定openrig apply --config ./project-a/openrig.yaml openrig apply --config ./project-b/openrig.yaml这样切换项目时配置也跟着切换不会互相干扰。配合 shell 的 alias 或者 direnv 这类工具进入项目目录自动应用对应配置体验会更顺滑。6.3 配置模板化与团队共享团队协作时可以把 openrig 配置做成模板密钥部分全部用环境变量占位。新成员拉下配置后只需要设置自己的环境变量然后openrig apply就能得到一致的开发环境。这比每个人手动配一遍要可靠得多也避免了“我这里能跑你那里不行”的扯皮。模板里还可以加注释说明每个端点的用途、申请方式、注意事项新人一看就懂。这也是 YAML 支持注释带来的实际收益。6.4 后续可以扩展的方向从 openrig 这个思路往外延还有不少可以做的。比如加一个openrig doctor命令自动检查环境、验证端点连通性、比对配置和实际生效状态再比如加配置版本迁移当工具配置格式变化时自动转换旧配置。这些都是在实际使用中会自然产生的需求。我个人在实际操作中的体会是这类配置编排工具的价值随着你使用的 AI 工具数量增加而指数级上升。一个工具时手动配无所谓三个五个工具时没有统一管理层就是灾难。openrig 这类工具解决的正是这个规模问题早点用起来后面省的心力远超前期学习成本。