1. 从 openrig 说起一个把 Claude Code 和 Codex 装进同一套工作流的开源脚手架第一次看到 openrig 这个名字我下意识把它拆成了 open 和 rig 两半。rig 在工程语境里是“装配、搭台子”的意思比如 test rig 就是测试台架。所以 openrig 本质上就是一套“开放装配台”——它要解决的不是某个单点功能而是把 Claude Code、Codex 这类命令行 AI 编程工具连同 YAML 配置、Node.js 运行时、本地模型接入这些零散环节装配成一套能稳定跑起来的工作环境。我接触 Claude Code 和 Codex 的时间不算短踩过的坑也足够多。最开始装 Claude Code 的时候卡在 Node.js 版本上整整一个下午后来想用 Codex 接入本地模型又被 YAML 配置里的缩进和字段名折腾得够呛。这些经历让我意识到单个工具的安装教程网上一搜一大把但真正难的是“让它们在同一台机器上和平共处”并且配置能复用、能迁移、能版本管理。openrig 想做的恰好就是这件事。这篇文章适合三类人看第一类是刚听说 Claude Code 或 Codex想上手但被环境配置劝退的新手第二类是已经在用其中一个工具想再接入另一个或者接本地模型的中级用户第三类是想把 AI 编程工具纳入团队标准化流程的工程负责人。我会从整体设计思路讲起然后拆解核心配置细节再给出完整的实操流程最后把我踩过的坑整理成排查表。全文基于我自己的实践和常见社区方案补充不保证是唯一解但保证是能跑通的解。2. openrig 的整体设计思路与方案选型2.1 为什么需要一层“装配层”而不是各装各的很多人会问Claude Code 和 Codex 各自都有官方安装方式为什么还要搞一个 openrig 这样的东西我一开始也这么想直到我在三台机器上重复配置了同样的环境每次都要重新回忆 Node.js 装哪个版本、YAML 放哪个目录、环境变量怎么设。这种重复劳动本身就是浪费更麻烦的是不同机器上的配置一旦出现细微差异排查起来极其痛苦。openrig 的核心价值在于“收敛”。它把散落在各处的配置项收敛到一套 YAML 文件里把运行时依赖收敛到统一的 Node.js 版本管理策略上把模型接入方式收敛成可切换的 provider 配置。这样一来你换机器只需要拷贝配置目录团队协作只需要共享一份 YAML出问题只需要看一个地方。这种收敛带来的可维护性提升远比省下几次安装时间更有价值。从架构上看openrig 大致分三层最底层是运行时层负责 Node.js 版本和全局包管理中间是配置层用 YAML 描述模型 provider、工具行为、路径映射最上层是工具层也就是 Claude Code、Codex 这些实际执行任务的 CLI。三层之间通过环境变量和配置文件解耦任何一层出问题都不会直接拖垮另外两层。这个分层思路是我认为 openrig 最值得借鉴的地方哪怕你不用它自己搭环境时也应该按这个思路来。2.2 工具选型背后的取舍逻辑在工具选型上openrig 选择同时支持 Claude Code 和 Codex而不是二选一这个决定背后有实际考量。Claude Code 在长上下文理解和多文件重构上表现稳定适合处理跨文件的复杂改动Codex 在单文件生成和快速补全上响应更快适合边写边改的场景。两者定位不同同时装并不冲突反而能覆盖更多工作场景。Node.js 作为运行时是几乎必然的选择因为 Claude Code 和 Codex 的 CLI 都是基于 Node.js 生态分发的。这里有个关键决策点用 LTS 版本还是最新版我的建议是坚决用 LTS。热词里有一条 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”这就是典型的版本踩坑案例——有人照着非官方渠道的版本号去装结果发现根本不存在。LTS 版本经过长期验证和主流 CLI 工具的兼容性最好没必要为了追新去冒风险。YAML 作为配置格式也是合理选择。相比 JSONYAML 支持注释这对需要写大量说明的配置文件来说太重要了相比 TOMLYAML 在嵌套结构上的表达更直观。当然 YAML 的缩进敏感也是出了名的坑后面我会专门讲怎么规避。2.3 本地模型接入的定位openrig 支持接入本地模型这一点在热词里也有体现比如 “claude code 调用 lmstudio 的本地模型”。为什么要接本地模型最直接的原因是成本和隐私。有些代码涉及内部逻辑不方便走云端有些场景调用频率高走云端成本吃不消。本地模型虽然能力上限不如云端大模型但在特定任务上已经够用。接入本地模型的关键在于接口兼容。大多数本地推理工具都提供 OpenAI 兼容的 API 端点openrig 通过配置 base_url 和 api_key 就能把请求转发过去。这里要注意的是本地模型的上下文窗口通常比云端小配置时需要相应调整 max_tokens 和截断策略否则容易出现请求被截断或者超时的问题。3. 核心配置细节与 YAML 实操要点3.1 YAML 文件的结构设计与字段含义openrig 的配置文件通常放在项目根目录或者用户主目录下的隐藏目录里具体位置取决于你的使用习惯。我倾向于放在项目根目录因为这样配置能跟着项目走换机器 clone 下来就能用。一份典型的配置大概长这样version: 1 runtime: node: 20.11.0 package_manager: npm providers: - name: claude type: anthropic api_key: ${ANTHROPIC_API_KEY} model: claude-sonnet-4-20250514 - name: codex type: openai base_url: https://api.openai.com/v1 api_key: ${OPENAI_API_KEY} model: gpt-4o - name: local type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: local-no-key model: qwen2.5-coder-7b tools: claude-code: provider: claude max_tokens: 8192 codex: provider: codex max_tokens: 4096这份配置里version 是配置格式版本方便后续做兼容升级。runtime 段声明 Node.js 版本和包管理器openrig 会据此检查环境。providers 段是核心每个 provider 描述一个模型来源type 决定用哪种协议去调用。tools 段把具体工具和 provider 绑定同时可以覆盖 max_tokens 这类参数。字段设计上有几个细节值得说。api_key 用${VAR}的形式引用环境变量而不是直接写明文这是基本的安全习惯。base_url 只在非官方端点时才需要写官方端点可以省略。model 字段写具体模型名不同 provider 的命名规则不一样写错会直接报模型不存在。3.2 YAML 缩进与常见语法陷阱YAML 最坑的地方就是缩进。它用缩进表示层级而且不允许用 Tab只能用空格。我见过太多次因为编辑器自动把空格转成 Tab 导致解析失败的案例。解决办法很简单在编辑器里把 YAML 文件的缩进统一设为 2 个空格并开启“显示空白字符”这样 Tab 和空格一眼就能看出来。另一个常见陷阱是冒号后面必须跟空格。name:claude和name: claude在 YAML 里是完全不同的东西前者会被解析成一个字符串而不是键值对。还有列表项的短横线后面也要跟空格-name和- name同理。这些细节在写配置时稍不注意就会出错而报错信息往往又很模糊只告诉你“解析失败”却不告诉你哪一行。字符串里的特殊字符也需要处理。如果值里包含冒号、井号或者以特殊符号开头最好用引号包起来。比如model: claude-sonnet-4-20250514加引号更保险。井号在 YAML 里是注释符号如果值里真的有井号不加引号会被截断。提示写完 YAML 后用python -c import yaml; yaml.safe_load(open(config.yaml))快速验证语法比等到工具报错再排查高效得多。3.3 环境变量与密钥管理把密钥写在 YAML 里是新手最容易犯的错误。一旦配置文件被提交到代码仓库密钥就泄露了。正确做法是用环境变量YAML 里只写引用。在 Linux 和 macOS 上可以把 export 语句写进 shell 的配置文件在 Windows 上用系统环境变量或者 PowerShell 的 profile 来设置。环境变量的命名建议加统一前缀比如OPENRIG_CLAUDE_KEY、OPENRIG_CODEX_KEY这样在系统里一眼就能认出是哪个工具用的。如果团队协作可以把环境变量的清单写成一个.env.example文件只写变量名不写值新人照着填就行。对于本地模型api_key 通常随便填一个非空字符串就行因为本地服务一般不校验。但有些 OpenAI 兼容实现会检查这个字段是否存在所以别留空。4. 完整实操流程从零搭起 openrig 环境4.1 Node.js 运行时的安装与版本管理第一步是装 Node.js。这里我强烈建议不要直接从官网下载安装包双击安装而是用版本管理工具。Linux 和 macOS 上用 nvmWindows 上用 nvm-windows 或者 fnm。版本管理工具的好处是可以在不同项目间切换 Node.js 版本而且升级和卸载都干净。用 nvm 安装 LTS 版本的命令是nvm install --lts然后nvm use --lts切换过去。装完后用node -v和npm -v确认版本。如果之前装过其他版本用nvm ls看看当前有哪些避免版本混乱。热词里那条 “error installing 24.21.0” 的报错根源就是有人手动指定了一个不存在的版本号。用nvm install --lts让工具自己去解析最新 LTS就不会有这个问题。如果你确实需要特定版本先去 Node.js 官方发布页确认版本号真实存在再装。Windows 用户要注意nvm-windows 和 nvm 是两个不同的项目命令有差异。nvm-windows 安装后需要以管理员身份运行才能切换版本而且它管理的 Node.js 是全局的不像 nvm 那样有 per-shell 的概念。如果嫌麻烦fnm 在 Windows 上体验更好支持自动切换。4.2 Claude Code 与 Codex 的安装与验证Node.js 就绪后装 Claude Code 和 Codex 就是一条命令的事。Claude Code 通常通过 npm 全局安装Codex 也是类似方式。装完后先别急着配模型用--version或者--help确认命令能正常执行。npm install -g anthropic-ai/claude-code npm install -g openai/codex claude --version codex --version如果安装过程中报权限错误Linux 和 macOS 上不要用 sudo 硬装而是配置 npm 的全局目录到用户目录下。Windows 上如果报 “无法加载组织设置” 这类错误通常是权限或者路径问题检查一下 npm 的 prefix 配置。验证阶段有个小技巧先不接任何模型直接跑一个最简单的命令看工具本身能不能启动。比如 Claude Code 跑claude --helpCodex 跑codex --help。如果这一步就失败说明是安装问题而不是配置问题排查方向就明确了。4.3 接入云端模型与本地模型的配置差异接云端模型相对简单拿到 API key填进环境变量YAML 里引用一下就行。接本地模型稍微复杂一点因为要先把本地推理服务跑起来。以常见的本地推理工具为例启动后它会监听一个端口提供 OpenAI 兼容的接口。你需要在 YAML 里把 base_url 指向这个端口model 填本地加载的模型名。本地模型接入最容易出问题的地方是上下文长度。云端模型动辄 128K 甚至 200K 上下文本地模型可能只有 8K 或 32K。如果配置里 max_tokens 设得太大请求会直接被本地服务拒绝。我的做法是先把 max_tokens 设小一点比如 2048跑通后再逐步往上调找到本地服务的实际上限。另一个差异是响应速度。本地模型受限于硬件生成速度可能比云端慢很多。如果工具本身有超时设置需要相应调大否则会出现请求还没返回就被判定超时的情况。4.4 在 VS Code 中集成与调用很多人习惯在 VS Code 里写代码所以把 Claude Code 和 Codex 集成进 VS Code 是刚需。集成方式有两种一种是用 VS Code 的终端直接跑 CLI另一种是装对应的扩展。前者通用性更强后者体验更顺滑。用终端的方式就是在 VS Code 里打开集成终端直接敲claude或codex命令。这种方式的好处是配置和命令行完全一致不会出现扩展和 CLI 配置不同步的问题。缺点是每次都要手动敲命令。装扩展的方式VS Code 市场里有 Claude Code 和 Codex 的相关扩展。装完后在设置里填 API key 和模型参数。这里要注意扩展的配置和 CLI 的配置是两套改了一边另一边不会自动同步。我的建议是统一用 CLI 配置扩展只作为快捷入口配置项尽量少填让它去读环境变量。注意VS Code 扩展有时会缓存配置改完 YAML 后需要重启 VS Code 或者重新加载窗口才能生效。如果改了配置没反应先试试重启。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解决安装阶段最高频的问题就是 Node.js 版本不匹配。表现是 npm install 时报 engine 相关的错误或者装完后命令跑不起来。解决办法是用 nvm 切到 LTS 版本然后删掉 node_modules 和 package-lock.json 重新装。第二个高频问题是网络导致的下载失败。npm 默认源在某些网络环境下会很慢甚至超时。可以临时切换到国内镜像源装完再切回来。命令是npm config set registry https://registry.npmmirror.com恢复用npm config set registry https://registry.npmjs.org。第三个问题是权限。Linux 和 macOS 上如果 npm 全局目录属于 root普通用户装包会报 EACCES。解决办法是npm config set prefix ~/.npm-global然后把~/.npm-global/bin加进 PATH。Windows 上则是检查是否以管理员身份运行了终端。5.2 配置加载失败的排查路径配置加载失败的表现通常是工具启动时报“无法解析配置”或者“找不到 provider”。排查顺序应该是先确认 YAML 语法正确再确认文件路径正确最后确认环境变量存在。YAML 语法用前面说的 python 命令验证。文件路径方面不同工具找配置的默认位置不一样有的找当前目录有的找用户主目录。最稳妥的办法是在 YAML 里显式指定配置路径或者用环境变量告诉工具去哪找。环境变量方面常见错误是在一个终端里 export 了换一个终端就没了。解决办法是写进 shell 配置文件或者用 direnv 这类工具做目录级的环境变量管理。5.3 模型调用异常的定位方法模型调用异常分几类认证失败、模型不存在、超时、返回格式错误。认证失败通常是 key 错了或者过期了检查环境变量里的值有没有多余空格。模型不存在是 model 字段写错了去 provider 的文档确认准确的模型名。超时问题在本地模型上尤其常见。先确认本地服务是否真的在跑用 curl 直接打一下接口看有没有响应。如果有响应但工具报超时就是工具的 timeout 设得太小调大即可。返回格式错误比较隐蔽通常是本地模型的输出不符合 OpenAI 格式规范。有些本地推理工具需要加特定参数才会返回标准格式查一下它的文档在启动参数里加上。5.4 常见问题速查表问题现象可能原因排查动作解决方式npm install 报 engine 错误Node.js 版本不匹配node -v确认版本用 nvm 切到 LTS命令找不到全局 bin 目录不在 PATHecho $PATH检查把 npm 全局 bin 加进 PATH配置解析失败YAML 缩进或语法错误python yaml.safe_load 验证修正缩进冒号后加空格认证失败API key 错误或缺失检查环境变量重新设置正确的 key模型不存在model 字段写错对照 provider 文档改成正确的模型名请求超时本地模型慢或 timeout 太小curl 直接测接口调大 timeout检查本地服务返回格式错误本地模型输出不规范看原始返回内容加兼容参数或换模型改了配置不生效工具缓存了旧配置重启工具重启或重新加载5.5 我踩过的几个坑和独家经验第一个坑是 YAML 里的布尔值陷阱。YAML 会把yes、no、on、off自动解析成布尔值如果你本来想写字符串就会出问题。比如某个字段值想写no结果被解析成 false。解决办法是加引号写成no。第二个坑是环境变量在 Windows 上的大小写。Windows 的环境变量不区分大小写但 Node.js 读的时候区分。如果你在 YAML 里写${Api_Key}而系统里设的是API_KEY在 Linux 上能读到在 Windows 上可能读不到。统一用大写最保险。第三个坑是本地模型的并发限制。有些本地推理服务默认只允许一个并发请求如果你同时开了 Claude Code 和 Codex 都指向它第二个请求会排队甚至被拒。解决办法是给每个工具配不同的本地服务实例或者调大本地服务的并发数。第四个坑是配置文件的编码。YAML 文件必须是 UTF-8 编码如果编辑器保存成了 GBK中文注释会乱码严重时导致解析失败。在编辑器里确认编码设置统一用 UTF-8。第五个坑是版本升级后的配置不兼容。工具升级后可能改了配置字段名或者结构旧配置直接失效。我的做法是升级前先备份配置升级后对照更新日志检查有没有 breaking change。openrig 的 version 字段就是为这个准备的不同版本走不同的解析逻辑。6. 把 openrig 用顺之后的几点体会用顺 openrig 之后我最大的感受是“配置即文档”。一份写清楚的 YAML比任何口头交接都管用。新人拿到配置照着装一遍就能跑起来不用再问“你当时是怎么配的”。这种可复现性对团队来说价值巨大。另一个体会是不要追求一次配到完美。我一开始想把所有 provider 都配上结果配置复杂到自己都记不住。后来改成按需配置常用的两三个 provider 写进去其他的等真要用再加。配置越简单出问题的概率越低。最后分享一个小技巧把常用的排查命令写成一个 shell 脚本比如检查 Node.js 版本、验证 YAML 语法、测试模型接口连通性。出问题时跑一遍脚本大部分低级问题当场就能定位。这个脚本我放在项目根目录团队里谁都能用省下了大量重复沟通的时间。这套东西后续还能往两个方向扩展。一是把配置模板化不同项目用不同的 profile启动时指定 profile 就行。二是把环境检查做成 CI 的一环提交配置前自动验证语法和连通性避免把坏配置合进主干。这两个方向我都在试等跑通了再单独写一篇。