1. 从 openrig 说起一个被低估的本地 AI 编码环境编排工具第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者机械臂项目实际上它解决的是一个非常具体、也非常痛的问题把 Claude Code、Codex 这类 AI 编码助手和本地模型、第三方 API、YAML 配置、Node.js 运行时这一整套东西编排成一个可复用、可切换、可版本管理的开发环境。说白了openrig 就是给“AI 编码工具链”做机架rig的那一层。我自己从 Claude Code 刚开放命令行版本的时候就开始折腾中间踩过的坑包括但不限于Node.js 版本不对导致安装直接报错、YAML 配置文件缩进错一格整个工具起不来、Codex 和 Claude Code 抢同一个端口、本地模型接进来之后响应格式对不上。这些问题单看都很小但叠在一起足够让一个下午报废。openrig 这类工具的价值就是把这些零散的配置、启动脚本、模型接入参数收敛到一个统一的编排层里。这篇文章适合三类人看第一类是想用 Claude Code 或 Codex 但被环境配置卡住的新手第二类是想把本地模型比如通过 LM Studio 跑的模型接进 AI 编码工具的中级用户第三类是需要在团队里统一管理多套 AI 编码环境、希望用 YAML 做声明式配置的工程负责人。全文围绕 openrig 这个核心把 Claude Code、Codex、YAML、Node.js 这几条线串起来讲清楚每个环节都会给出可复现的操作和参数说明。需要先说明一点openrig 本身是一个编排思路的载体不同团队落地时具体形态可能不同有人用 shell 脚本有人用 Node.js 写 CLI有人直接用 YAML 加一个启动器。下面讲的内容是基于“一个合格从业者在搭建本地 AI 编码环境时最可能采用的合理方案”来展开的重点在于思路和细节而不是绑定某一个具体实现。2. 整体设计思路为什么要把 AI 编码工具“机架化”2.1 核心痛点工具越多环境越乱Claude Code 和 Codex 这两个工具单独装一个都不算难。Claude Code 官方给了 npm 安装方式Codex 也有自己的 CLI 和桌面版。但问题在于当你同时用两个、三个甚至更多 AI 编码工具并且还要在本地模型和云端 API 之间切换时环境就开始失控了。我遇到过最典型的情况是Claude Code 需要某个版本的 Node.jsCodex 的 CLI 对 Node.js 版本要求又不一样两个工具装在同一个全局环境里升级一个就弄坏另一个。再加上 YAML 配置文件散落在用户目录、项目目录、工具自己的配置目录里改了一个忘了另一个排查起来非常痛苦。openrig 的第一个设计目标就是把这些运行时依赖和配置路径全部隔离。隔离的手段其实不复杂用 Node.js 的版本管理工具比如 nvm 或 fnm给每个工具锁定独立的 Node.js 版本用独立的配置目录存放各自的 YAML再用一个统一的入口脚本负责启动和切换。这样 Claude Code 和 Codex 互不干扰本地模型和云端 API 的切换也变成改一个 YAML 字段的事。2.2 声明式配置YAML 为什么是首选在 openrig 的设计里YAML 承担了“唯一事实来源”的角色。为什么不用 JSON 或者 TOMLJSON 不支持注释配置一多就没法维护TOML 表达嵌套结构时比较啰嗦。YAML 的优势在于可读性好、支持注释、嵌套结构清晰而且 Claude Code 和 Codex 的很多周边工具本身就吃 YAML生态是通的。一个典型的 openrig YAML 配置大概长这样version: 1 runtime: node: 20.11.0 package_manager: npm tools: claude-code: enabled: true config_dir: ./configs/claude model_provider: local codex: enabled: true config_dir: ./configs/codex model_provider: cloud providers: local: base_url: http://127.0.0.1:1234/v1 model: local-coder cloud: base_url: https://api.example.com/v1 model: remote-coder这份配置里runtime 段锁定 Node.js 版本tools 段声明启用哪些工具以及各自的配置目录providers 段定义模型来源。切换本地模型和云端模型只需要改 model_provider 这一个字段。这就是声明式配置的好处状态清晰改动可追溯团队里每个人拿到的环境是一致的。注意YAML 对缩进极其敏感必须用空格不能用 Tab。我见过太多次因为编辑器自动把 Tab 转成空格、或者反过来导致配置文件解析失败的情况。建议在项目里放一个 .editorconfig强制 YAML 文件使用 2 空格缩进。2.3 方案选型背后的取舍有人会问为什么不直接写一个 Docker 镜像把所有东西打包进去Docker 确实能解决隔离问题但对于 AI 编码工具来说本地模型往往需要访问宿主机的 GPU 和本地端口容器化之后网络和硬件访问会变复杂。而且 Claude Code 和 Codex 都需要频繁读写项目文件挂载卷的权限问题也很烦。所以 openrig 选择的是“轻量编排”路线不引入容器用 Node.js 版本隔离加配置目录隔离来达到类似效果代价是需要在宿主机上装好 Node.js 版本管理工具。另一个取舍是配置的存放位置。放在项目目录里好处是跟着代码走团队共享方便坏处是容易误提交包含密钥的配置。放在用户目录里好处是安全坏处是团队同步麻烦。我的做法是分两层项目目录里放不含密钥的模板配置用户目录里放实际的密钥和本地路径覆盖启动时合并。这样既能共享又不会泄露敏感信息。3. 核心细节解析Node.js、YAML 与工具接入的实操要点3.1 Node.js 版本管理别再用系统自带的Claude Code 和 Codex 的 CLI 都是 Node.js 生态的工具Node.js 版本选错轻则警告重则直接安装失败。热搜词里出现的 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型的版本号写错或者源里没有这个版本导致的。我的建议是永远不要用系统包管理器装的 Node.js用 nvm 或 fnm 管理。以 fnm 为例安装和切换版本的操作如下# 安装 fnm以常见方式为例 curl -fsSL https://fnm.vercel.app/install | bash # 安装指定版本的 Node.js fnm install 20.11.0 # 在当前 shell 使用该版本 fnm use 20.11.0 # 验证 node -v npm -v为什么推荐 20.x LTS 而不是最新的 24.x因为 Claude Code 和 Codex 的很多依赖在 LTS 版本上测试最充分最新的奇数版本或者刚发布的版本生态适配往往滞后。热搜里那个 “24.21.0 is not yet released” 的报错本质上是版本号不存在不是工具的问题。选 LTS 能避开大量这类坑。在 openrig 的 YAML 里runtime.node 字段就是用来声明这个版本的。启动脚本读取这个字段自动调用 fnm use 切换到对应版本再执行工具命令。这样团队成员不需要记住每个工具要哪个版本配置说了算。3.2 YAML 配置的层级设计与常见陷阱openrig 的 YAML 配置不是随便写的它需要覆盖几个层级运行时层、工具层、模型提供方层、以及可选的覆盖层。层级设计的原则是“越靠下越具体越靠上越通用”。运行时层最通用模型提供方层最具体。写 YAML 时有几个高频陷阱我整理成表格方便对照陷阱类型具体表现正确做法缩进错误用 Tab 或缩进不一致统一 2 空格配 .editorconfig冒号后缺空格key:value解析失败写成key: value布尔值歧义yes/no/on/off被解析成布尔显式写true/false多行字符串用 和 混淆锚点引用合并键时覆盖顺序错明确合并优先级其中布尔值歧义是最隐蔽的。YAML 1.1 规范里yes、no、on、off都会被解析成布尔值但很多解析器用的是 YAML 1.2只认true和false。如果你的配置里写了enabled: yes在不同工具里行为可能不一致。所以我一律显式写true或false不给解析器留歧义空间。3.3 Claude Code 与 Codex 的接入差异Claude Code 和 Codex 虽然都是 AI 编码工具但接入方式有差异。Claude Code 更偏向命令行交互配置主要通过环境变量和配置文件Codex 有 CLI 也有桌面版配置入口更多。在 openrig 里这两者被抽象成 tools 下的两个条目各自指向独立的 config_dir。Claude Code 接入本地模型时关键是把 base_url 指向本地服务的地址比如 LM Studio 默认的http://127.0.0.1:1234/v1。Codex 接入第三方 API 时需要确认 API 的响应格式和 Codex 期望的格式一致否则会出现 “ignoring 1 unrecognized configuration setting” 这类警告。这个警告的意思是配置文件里有一个它不认识的字段通常是字段名拼写错误或者版本不匹配。提示遇到 “unrecognized configuration setting” 时先对照官方文档确认字段名再确认工具版本。很多情况下是配置字段在新版本里改名了旧配置没跟着更新。4. 实操过程从零搭一套 openrig 环境4.1 环境准备与依赖安装第一步是把基础依赖装好。假设你用的是 Ubuntu 或者 macOS操作大同小异。先装 fnm 管理 Node.js再装一个 YAML 解析工具方便校验配置最后装 Claude Code 和 Codex。# 安装 fnm curl -fsSL https://fnm.vercel.app/install | bash # 让 fnm 在当前 shell 生效 eval $(fnm env --use-on-cd) # 安装 Node.js 20 LTS fnm install 20 fnm use 20 # 全局安装 Claude Code以 npm 包为例 npm install -g anthropic-ai/claude-code # 安装 Codex CLI以 npm 包为例 npm install -g openai/codex装完之后验证一下claude --version codex --version如果这两个命令都能输出版本号说明基础环境没问题。如果报 “command not found”大概率是 npm 全局 bin 目录不在 PATH 里用npm config get prefix看一下路径把它加到 PATH 里。4.2 编写 openrig 的 YAML 配置接下来写 openrig 的核心配置文件。我习惯放在项目根目录的openrig.yaml内容如下version: 1 runtime: node: 20 package_manager: npm tools: claude-code: enabled: true config_dir: ./configs/claude model_provider: local env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234/v1 codex: enabled: true config_dir: ./configs/codex model_provider: cloud providers: local: base_url: http://127.0.0.1:1234/v1 model: local-coder api_key: not-needed cloud: base_url: https://api.example.com/v1 model: remote-coder api_key: ${CLOUD_API_KEY} overrides: - path: ./openrig.local.yaml optional: true这份配置里${CLOUD_API_KEY}是环境变量占位符实际密钥从环境变量读取不写死在文件里。overrides段允许用一个本地文件覆盖配置这个文件加到 .gitignore 里用来放个人路径和密钥。4.3 启动脚本与模型切换openrig 的启动脚本负责读 YAML、切 Node.js 版本、设置环境变量、启动工具。用 Node.js 写一个简单的启动器const fs require(fs); const yaml require(js-yaml); const { execSync } require(child_process); const config yaml.load(fs.readFileSync(openrig.yaml, utf8)); // 切换 Node.js 版本 execSync(fnm use ${config.runtime.node}, { stdio: inherit }); // 启动指定工具 const toolName process.argv[2] || claude-code; const tool config.tools[toolName]; if (!tool || !tool.enabled) { console.error(工具 ${toolName} 未启用); process.exit(1); } const provider config.providers[tool.model_provider]; const env { ...process.env, ...tool.env, BASE_URL: provider.base_url, MODEL: provider.model, }; execSync(toolName claude-code ? claude : codex, { stdio: inherit, env, });这个脚本的核心逻辑是读配置、切版本、合并环境变量、启动工具。切换模型只需要改 YAML 里的model_provider字段从local改成cloud再跑一次启动脚本就行。4.4 本地模型接入的验证本地模型接入最容易出问题的地方是响应格式。以 LM Studio 为例它默认提供 OpenAI 兼容的接口但有些模型对 system prompt 的处理和云端模型不一样。验证方法是先用 curl 直接打本地接口curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d { model: local-coder, messages: [{role: user, content: print hello}] }如果这个请求能正常返回说明本地服务没问题。如果 Claude Code 或 Codex 还是报错那就是工具侧的配置问题重点检查 base_url 是否带了/v1后缀、api_key 是否为空字符串而不是缺失。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错安装阶段最高频的报错就是 Node.js 版本问题。热搜里那个 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available” 就是版本号不存在。解决办法很简单用fnm ls-remote看一下有哪些可用版本选一个实际存在的 LTS 版本。另一个常见问题是权限。在 Linux 上用 npm 全局安装时如果没配好 prefix会报 EACCES 权限错误。解决办法是配置 npm 的全局目录到用户目录下npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH这样就不需要 sudo 了也避免了污染系统目录。5.2 配置加载失败的排查顺序配置加载失败时按这个顺序排查效率最高先用 YAML 校验工具检查语法比如python -c import yaml; yaml.safe_load(open(openrig.yaml))。确认缩进和冒号后的空格。确认环境变量占位符对应的变量已经设置。确认 overrides 文件路径存在如果 optional 为 false。确认工具版本和配置字段匹配。这个顺序是从“语法层”到“语义层”再到“环境层”能覆盖绝大多数问题。5.3 模型切换后行为异常的定位从云端模型切到本地模型后如果工具行为异常比如回复变短、不执行命令、或者直接报格式错误通常是这几个原因本地模型的上下文窗口比云端小长对话被截断本地模型对工具调用的格式支持不完整base_url 配置错误导致请求打到了错误的服务。排查方法是先看工具的日志输出确认请求实际发到了哪个地址。Claude Code 和 Codex 一般都有 verbose 模式打开之后能看到完整的请求和响应。如果请求地址不对检查 YAML 里的 base_url 和工具自身的环境变量是否有冲突环境变量的优先级通常高于配置文件。5.4 常见问题速查表问题现象可能原因解决方向安装报版本不存在Node.js 版本号写错用 fnm ls-remote 查可用版本配置解析失败YAML 缩进或冒号问题用校验工具逐行检查工具启动即退出Node.js 版本不匹配检查 runtime.node 字段本地模型无响应base_url 或端口错误curl 直接测试接口切换模型后报格式错模型不支持工具调用格式换模型或调整 prompt密钥泄露风险密钥写死在 YAML改用环境变量占位符5.5 几个踩过坑才明白的细节第一个细节fnm 的--use-on-cd功能很好用但如果你在脚本里用execSync调用 fnm它不会自动生效必须显式fnm use。我一开始以为配了--use-on-cd就万事大吉结果脚本里 Node.js 版本还是系统的旧版本排查了半天。第二个细节YAML 里的环境变量占位符不同解析器支持程度不一样。js-yaml 默认不解析${VAR}需要自己写替换逻辑。我后来统一在启动脚本里做一层字符串替换把${VAR}替换成process.env.VAR这样最可控。第三个细节Claude Code 和 Codex 的配置目录如果指向同一个路径会互相覆盖配置。openrig 里给每个工具分配独立的 config_dir就是为了避免这个问题。这个设计看起来多余实际上是血泪教训。6. 团队协作与配置版本管理6.1 配置分层模板与实例分离团队里用 openrig最大的挑战是配置同步。我的做法是把配置分成两层openrig.yaml是模板提交到仓库不含任何密钥和个人路径openrig.local.yaml是实例配置加到 .gitignore每个人自己维护。启动脚本先读模板再用实例配置覆盖。这样新人入职时只需要复制一份openrig.local.example.yaml填上自己的密钥和路径就能跑起来。模板更新时通过 git pull 同步不会覆盖个人配置。6.2 版本锁定与升级策略Node.js 版本、Claude Code 版本、Codex 版本这三个都需要锁定。Node.js 版本在 YAML 里锁工具版本建议在 package.json 里锁。如果工具是通过 npm 全局安装的可以在项目里放一个package.json把工具作为 devDependencies用npx调用这样版本跟着项目走。升级策略上我建议每个季度评估一次先在个人环境验证新版本确认没问题再更新模板里的版本号。不要盲目追新AI 编码工具的迭代很快新版本引入回归问题的概率不低。6.3 多环境切换的实践一个团队往往有多个环境开发、测试、生产。openrig 的 providers 段可以定义多个提供方通过环境变量或者命令行参数选择。比如OPENRIG_ENVdev node openrig.js claude-code OPENRIG_ENVprod node openrig.js codex启动脚本根据OPENRIG_ENV读取对应的 provider 配置。这样同一套工具链在不同环境下用不同的模型和 API 地址切换成本极低。7. 扩展方向openrig 还能怎么用openrig 这套编排思路不局限于 Claude Code 和 Codex。任何需要多工具、多模型、多环境切换的场景都可以套用。比如你同时用多个 AI 编码助手或者需要在本地模型和多个云端 API 之间做 A/B 测试openrig 的 YAML 配置和启动脚本都能直接复用。再进一步可以把 openrig 和 CI 结合起来。在 CI 里用 openrig 拉起一个 AI 编码工具对代码做自动审查或者生成测试用例。这时候 YAML 里的 provider 指向 CI 环境可访问的 API配置通过环境变量注入整个流程是声明式的可复现的。我个人在实际操作中的体会是环境编排这件事前期多花一个小时把配置理清楚后期能省下几十个小时的排查时间。openrig 的价值不在于它有多复杂而在于它把散落各处的配置和依赖收敛到一个可读、可版本管理的地方。如果你现在还在手动改环境变量、手动切 Node.js 版本真的建议花点时间把这套东西搭起来一次投入长期受益。
1. 从 openrig 说起一个被低估的本地 AI 编码环境编排工具第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者机械臂项目实际上它解决的是一个非常具体、也非常痛的问题把 Claude Code、Codex 这类 AI 编码助手和本地模型、第三方 API、YAML 配置、Node.js 运行时这一整套东西编排成一个可复用、可切换、可版本管理的开发环境。说白了openrig 就是给“AI 编码工具链”做机架rig的那一层。我自己从 Claude Code 刚开放命令行版本的时候就开始折腾中间踩过的坑包括但不限于Node.js 版本不对导致安装直接报错、YAML 配置文件缩进错一格整个工具起不来、Codex 和 Claude Code 抢同一个端口、本地模型接进来之后响应格式对不上。这些问题单看都很小但叠在一起足够让一个下午报废。openrig 这类工具的价值就是把这些零散的配置、启动脚本、模型接入参数收敛到一个统一的编排层里。这篇文章适合三类人看第一类是想用 Claude Code 或 Codex 但被环境配置卡住的新手第二类是想把本地模型比如通过 LM Studio 跑的模型接进 AI 编码工具的中级用户第三类是需要在团队里统一管理多套 AI 编码环境、希望用 YAML 做声明式配置的工程负责人。全文围绕 openrig 这个核心把 Claude Code、Codex、YAML、Node.js 这几条线串起来讲清楚每个环节都会给出可复现的操作和参数说明。需要先说明一点openrig 本身是一个编排思路的载体不同团队落地时具体形态可能不同有人用 shell 脚本有人用 Node.js 写 CLI有人直接用 YAML 加一个启动器。下面讲的内容是基于“一个合格从业者在搭建本地 AI 编码环境时最可能采用的合理方案”来展开的重点在于思路和细节而不是绑定某一个具体实现。2. 整体设计思路为什么要把 AI 编码工具“机架化”2.1 核心痛点工具越多环境越乱Claude Code 和 Codex 这两个工具单独装一个都不算难。Claude Code 官方给了 npm 安装方式Codex 也有自己的 CLI 和桌面版。但问题在于当你同时用两个、三个甚至更多 AI 编码工具并且还要在本地模型和云端 API 之间切换时环境就开始失控了。我遇到过最典型的情况是Claude Code 需要某个版本的 Node.jsCodex 的 CLI 对 Node.js 版本要求又不一样两个工具装在同一个全局环境里升级一个就弄坏另一个。再加上 YAML 配置文件散落在用户目录、项目目录、工具自己的配置目录里改了一个忘了另一个排查起来非常痛苦。openrig 的第一个设计目标就是把这些运行时依赖和配置路径全部隔离。隔离的手段其实不复杂用 Node.js 的版本管理工具比如 nvm 或 fnm给每个工具锁定独立的 Node.js 版本用独立的配置目录存放各自的 YAML再用一个统一的入口脚本负责启动和切换。这样 Claude Code 和 Codex 互不干扰本地模型和云端 API 的切换也变成改一个 YAML 字段的事。2.2 声明式配置YAML 为什么是首选在 openrig 的设计里YAML 承担了“唯一事实来源”的角色。为什么不用 JSON 或者 TOMLJSON 不支持注释配置一多就没法维护TOML 表达嵌套结构时比较啰嗦。YAML 的优势在于可读性好、支持注释、嵌套结构清晰而且 Claude Code 和 Codex 的很多周边工具本身就吃 YAML生态是通的。一个典型的 openrig YAML 配置大概长这样version: 1 runtime: node: 20.11.0 package_manager: npm tools: claude-code: enabled: true config_dir: ./configs/claude model_provider: local codex: enabled: true config_dir: ./configs/codex model_provider: cloud providers: local: base_url: http://127.0.0.1:1234/v1 model: local-coder cloud: base_url: https://api.example.com/v1 model: remote-coder这份配置里runtime 段锁定 Node.js 版本tools 段声明启用哪些工具以及各自的配置目录providers 段定义模型来源。切换本地模型和云端模型只需要改 model_provider 这一个字段。这就是声明式配置的好处状态清晰改动可追溯团队里每个人拿到的环境是一致的。注意YAML 对缩进极其敏感必须用空格不能用 Tab。我见过太多次因为编辑器自动把 Tab 转成空格、或者反过来导致配置文件解析失败的情况。建议在项目里放一个 .editorconfig强制 YAML 文件使用 2 空格缩进。2.3 方案选型背后的取舍有人会问为什么不直接写一个 Docker 镜像把所有东西打包进去Docker 确实能解决隔离问题但对于 AI 编码工具来说本地模型往往需要访问宿主机的 GPU 和本地端口容器化之后网络和硬件访问会变复杂。而且 Claude Code 和 Codex 都需要频繁读写项目文件挂载卷的权限问题也很烦。所以 openrig 选择的是“轻量编排”路线不引入容器用 Node.js 版本隔离加配置目录隔离来达到类似效果代价是需要在宿主机上装好 Node.js 版本管理工具。另一个取舍是配置的存放位置。放在项目目录里好处是跟着代码走团队共享方便坏处是容易误提交包含密钥的配置。放在用户目录里好处是安全坏处是团队同步麻烦。我的做法是分两层项目目录里放不含密钥的模板配置用户目录里放实际的密钥和本地路径覆盖启动时合并。这样既能共享又不会泄露敏感信息。3. 核心细节解析Node.js、YAML 与工具接入的实操要点3.1 Node.js 版本管理别再用系统自带的Claude Code 和 Codex 的 CLI 都是 Node.js 生态的工具Node.js 版本选错轻则警告重则直接安装失败。热搜词里出现的 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型的版本号写错或者源里没有这个版本导致的。我的建议是永远不要用系统包管理器装的 Node.js用 nvm 或 fnm 管理。以 fnm 为例安装和切换版本的操作如下# 安装 fnm以常见方式为例 curl -fsSL https://fnm.vercel.app/install | bash # 安装指定版本的 Node.js fnm install 20.11.0 # 在当前 shell 使用该版本 fnm use 20.11.0 # 验证 node -v npm -v为什么推荐 20.x LTS 而不是最新的 24.x因为 Claude Code 和 Codex 的很多依赖在 LTS 版本上测试最充分最新的奇数版本或者刚发布的版本生态适配往往滞后。热搜里那个 “24.21.0 is not yet released” 的报错本质上是版本号不存在不是工具的问题。选 LTS 能避开大量这类坑。在 openrig 的 YAML 里runtime.node 字段就是用来声明这个版本的。启动脚本读取这个字段自动调用 fnm use 切换到对应版本再执行工具命令。这样团队成员不需要记住每个工具要哪个版本配置说了算。3.2 YAML 配置的层级设计与常见陷阱openrig 的 YAML 配置不是随便写的它需要覆盖几个层级运行时层、工具层、模型提供方层、以及可选的覆盖层。层级设计的原则是“越靠下越具体越靠上越通用”。运行时层最通用模型提供方层最具体。写 YAML 时有几个高频陷阱我整理成表格方便对照陷阱类型具体表现正确做法缩进错误用 Tab 或缩进不一致统一 2 空格配 .editorconfig冒号后缺空格key:value解析失败写成key: value布尔值歧义yes/no/on/off被解析成布尔显式写true/false多行字符串用 和 混淆锚点引用合并键时覆盖顺序错明确合并优先级其中布尔值歧义是最隐蔽的。YAML 1.1 规范里yes、no、on、off都会被解析成布尔值但很多解析器用的是 YAML 1.2只认true和false。如果你的配置里写了enabled: yes在不同工具里行为可能不一致。所以我一律显式写true或false不给解析器留歧义空间。3.3 Claude Code 与 Codex 的接入差异Claude Code 和 Codex 虽然都是 AI 编码工具但接入方式有差异。Claude Code 更偏向命令行交互配置主要通过环境变量和配置文件Codex 有 CLI 也有桌面版配置入口更多。在 openrig 里这两者被抽象成 tools 下的两个条目各自指向独立的 config_dir。Claude Code 接入本地模型时关键是把 base_url 指向本地服务的地址比如 LM Studio 默认的http://127.0.0.1:1234/v1。Codex 接入第三方 API 时需要确认 API 的响应格式和 Codex 期望的格式一致否则会出现 “ignoring 1 unrecognized configuration setting” 这类警告。这个警告的意思是配置文件里有一个它不认识的字段通常是字段名拼写错误或者版本不匹配。提示遇到 “unrecognized configuration setting” 时先对照官方文档确认字段名再确认工具版本。很多情况下是配置字段在新版本里改名了旧配置没跟着更新。4. 实操过程从零搭一套 openrig 环境4.1 环境准备与依赖安装第一步是把基础依赖装好。假设你用的是 Ubuntu 或者 macOS操作大同小异。先装 fnm 管理 Node.js再装一个 YAML 解析工具方便校验配置最后装 Claude Code 和 Codex。# 安装 fnm curl -fsSL https://fnm.vercel.app/install | bash # 让 fnm 在当前 shell 生效 eval $(fnm env --use-on-cd) # 安装 Node.js 20 LTS fnm install 20 fnm use 20 # 全局安装 Claude Code以 npm 包为例 npm install -g anthropic-ai/claude-code # 安装 Codex CLI以 npm 包为例 npm install -g openai/codex装完之后验证一下claude --version codex --version如果这两个命令都能输出版本号说明基础环境没问题。如果报 “command not found”大概率是 npm 全局 bin 目录不在 PATH 里用npm config get prefix看一下路径把它加到 PATH 里。4.2 编写 openrig 的 YAML 配置接下来写 openrig 的核心配置文件。我习惯放在项目根目录的openrig.yaml内容如下version: 1 runtime: node: 20 package_manager: npm tools: claude-code: enabled: true config_dir: ./configs/claude model_provider: local env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234/v1 codex: enabled: true config_dir: ./configs/codex model_provider: cloud providers: local: base_url: http://127.0.0.1:1234/v1 model: local-coder api_key: not-needed cloud: base_url: https://api.example.com/v1 model: remote-coder api_key: ${CLOUD_API_KEY} overrides: - path: ./openrig.local.yaml optional: true这份配置里${CLOUD_API_KEY}是环境变量占位符实际密钥从环境变量读取不写死在文件里。overrides段允许用一个本地文件覆盖配置这个文件加到 .gitignore 里用来放个人路径和密钥。4.3 启动脚本与模型切换openrig 的启动脚本负责读 YAML、切 Node.js 版本、设置环境变量、启动工具。用 Node.js 写一个简单的启动器const fs require(fs); const yaml require(js-yaml); const { execSync } require(child_process); const config yaml.load(fs.readFileSync(openrig.yaml, utf8)); // 切换 Node.js 版本 execSync(fnm use ${config.runtime.node}, { stdio: inherit }); // 启动指定工具 const toolName process.argv[2] || claude-code; const tool config.tools[toolName]; if (!tool || !tool.enabled) { console.error(工具 ${toolName} 未启用); process.exit(1); } const provider config.providers[tool.model_provider]; const env { ...process.env, ...tool.env, BASE_URL: provider.base_url, MODEL: provider.model, }; execSync(toolName claude-code ? claude : codex, { stdio: inherit, env, });这个脚本的核心逻辑是读配置、切版本、合并环境变量、启动工具。切换模型只需要改 YAML 里的model_provider字段从local改成cloud再跑一次启动脚本就行。4.4 本地模型接入的验证本地模型接入最容易出问题的地方是响应格式。以 LM Studio 为例它默认提供 OpenAI 兼容的接口但有些模型对 system prompt 的处理和云端模型不一样。验证方法是先用 curl 直接打本地接口curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d { model: local-coder, messages: [{role: user, content: print hello}] }如果这个请求能正常返回说明本地服务没问题。如果 Claude Code 或 Codex 还是报错那就是工具侧的配置问题重点检查 base_url 是否带了/v1后缀、api_key 是否为空字符串而不是缺失。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错安装阶段最高频的报错就是 Node.js 版本问题。热搜里那个 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available” 就是版本号不存在。解决办法很简单用fnm ls-remote看一下有哪些可用版本选一个实际存在的 LTS 版本。另一个常见问题是权限。在 Linux 上用 npm 全局安装时如果没配好 prefix会报 EACCES 权限错误。解决办法是配置 npm 的全局目录到用户目录下npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH这样就不需要 sudo 了也避免了污染系统目录。5.2 配置加载失败的排查顺序配置加载失败时按这个顺序排查效率最高先用 YAML 校验工具检查语法比如python -c import yaml; yaml.safe_load(open(openrig.yaml))。确认缩进和冒号后的空格。确认环境变量占位符对应的变量已经设置。确认 overrides 文件路径存在如果 optional 为 false。确认工具版本和配置字段匹配。这个顺序是从“语法层”到“语义层”再到“环境层”能覆盖绝大多数问题。5.3 模型切换后行为异常的定位从云端模型切到本地模型后如果工具行为异常比如回复变短、不执行命令、或者直接报格式错误通常是这几个原因本地模型的上下文窗口比云端小长对话被截断本地模型对工具调用的格式支持不完整base_url 配置错误导致请求打到了错误的服务。排查方法是先看工具的日志输出确认请求实际发到了哪个地址。Claude Code 和 Codex 一般都有 verbose 模式打开之后能看到完整的请求和响应。如果请求地址不对检查 YAML 里的 base_url 和工具自身的环境变量是否有冲突环境变量的优先级通常高于配置文件。5.4 常见问题速查表问题现象可能原因解决方向安装报版本不存在Node.js 版本号写错用 fnm ls-remote 查可用版本配置解析失败YAML 缩进或冒号问题用校验工具逐行检查工具启动即退出Node.js 版本不匹配检查 runtime.node 字段本地模型无响应base_url 或端口错误curl 直接测试接口切换模型后报格式错模型不支持工具调用格式换模型或调整 prompt密钥泄露风险密钥写死在 YAML改用环境变量占位符5.5 几个踩过坑才明白的细节第一个细节fnm 的--use-on-cd功能很好用但如果你在脚本里用execSync调用 fnm它不会自动生效必须显式fnm use。我一开始以为配了--use-on-cd就万事大吉结果脚本里 Node.js 版本还是系统的旧版本排查了半天。第二个细节YAML 里的环境变量占位符不同解析器支持程度不一样。js-yaml 默认不解析${VAR}需要自己写替换逻辑。我后来统一在启动脚本里做一层字符串替换把${VAR}替换成process.env.VAR这样最可控。第三个细节Claude Code 和 Codex 的配置目录如果指向同一个路径会互相覆盖配置。openrig 里给每个工具分配独立的 config_dir就是为了避免这个问题。这个设计看起来多余实际上是血泪教训。6. 团队协作与配置版本管理6.1 配置分层模板与实例分离团队里用 openrig最大的挑战是配置同步。我的做法是把配置分成两层openrig.yaml是模板提交到仓库不含任何密钥和个人路径openrig.local.yaml是实例配置加到 .gitignore每个人自己维护。启动脚本先读模板再用实例配置覆盖。这样新人入职时只需要复制一份openrig.local.example.yaml填上自己的密钥和路径就能跑起来。模板更新时通过 git pull 同步不会覆盖个人配置。6.2 版本锁定与升级策略Node.js 版本、Claude Code 版本、Codex 版本这三个都需要锁定。Node.js 版本在 YAML 里锁工具版本建议在 package.json 里锁。如果工具是通过 npm 全局安装的可以在项目里放一个package.json把工具作为 devDependencies用npx调用这样版本跟着项目走。升级策略上我建议每个季度评估一次先在个人环境验证新版本确认没问题再更新模板里的版本号。不要盲目追新AI 编码工具的迭代很快新版本引入回归问题的概率不低。6.3 多环境切换的实践一个团队往往有多个环境开发、测试、生产。openrig 的 providers 段可以定义多个提供方通过环境变量或者命令行参数选择。比如OPENRIG_ENVdev node openrig.js claude-code OPENRIG_ENVprod node openrig.js codex启动脚本根据OPENRIG_ENV读取对应的 provider 配置。这样同一套工具链在不同环境下用不同的模型和 API 地址切换成本极低。7. 扩展方向openrig 还能怎么用openrig 这套编排思路不局限于 Claude Code 和 Codex。任何需要多工具、多模型、多环境切换的场景都可以套用。比如你同时用多个 AI 编码助手或者需要在本地模型和多个云端 API 之间做 A/B 测试openrig 的 YAML 配置和启动脚本都能直接复用。再进一步可以把 openrig 和 CI 结合起来。在 CI 里用 openrig 拉起一个 AI 编码工具对代码做自动审查或者生成测试用例。这时候 YAML 里的 provider 指向 CI 环境可访问的 API配置通过环境变量注入整个流程是声明式的可复现的。我个人在实际操作中的体会是环境编排这件事前期多花一个小时把配置理清楚后期能省下几十个小时的排查时间。openrig 的价值不在于它有多复杂而在于它把散落各处的配置和依赖收敛到一个可读、可版本管理的地方。如果你现在还在手动改环境变量、手动切 Node.js 版本真的建议花点时间把这套东西搭起来一次投入长期受益。
