1. 从 openrig 这个标题说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的装置或工作台。放到当下 AI 编程助手满天飞的环境里这个名字其实指向一个很具体的痛点Claude Code、Codex 这类命令行 AI 编程工具各自为政配置格式不统一模型接入方式五花八门切换一次就要重配一遍环境。openrig 想做的就是把这些散落的东西用一个统一的、基于 YAML 的配置骨架“架”起来让你像搭积木一样把不同的模型后端、不同的 CLI 工具、不同的项目上下文拼装到同一套工作流里。我接触 Claude Code 和 Codex 有一段时间了踩过的坑不算少。最开始是 Claude Code 装不上Node.js 版本对不上后来是 Codex 登录报“组织已禁用订阅访问”再后来想接本地模型又卡在代理转发和 endpoint 配置上。这些问题的共同点是它们都不是模型本身的问题而是“装配”的问题。openrig 这个标题之所以值得单独拿出来聊就是因为它代表了一类需求——把 AI 编程工具的“装配层”标准化。这篇文章适合谁看如果你正在用或者准备用 Claude Code、Codex 这类 CLI 工具被 YAML 配置、Node.js 环境、模型接入这些事折腾过或者你想把本地模型比如通过 LM Studio 跑的模型接进这套流程那这篇内容基本就是给你写的。我会从整体设计思路讲到具体实操包括 YAML 怎么写、Node.js 环境怎么搭、Claude Code 和 Codex 怎么装怎么配、本地模型怎么接、报错怎么排查。不堆概念只讲我实际跑通的东西。需要先说明一点openrig 本身在公开资料里并不是一个已经定型的成熟项目更多是一个“方向性”的命名。所以下面涉及的具体配置和步骤是我基于 Claude Code、Codex 这类工具当前常见的装配实践做的合理补全你可以把它当成一套可复用的“装配方法论”而不是某个特定仓库的说明书。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 为什么配置层要选 YAML先说 YAML。很多人第一次接触 YAML 是在写 CI 配置、Docker Compose 或者 K8s 清单的时候觉得它“缩进敏感、容易写错”。但放到 AI 编程工具的配置场景里YAML 的优势非常明显它天生适合表达层级化的配置而且可读性比 JSON 好注释支持比 JSON 强。你想想 Claude Code 和 Codex 的配置需求要指定模型提供商、要指定 API endpoint、要指定模型名称、要指定超时和重试、要指定项目级别的上下文文件。这些天然就是嵌套结构。用 JSON 写满屏引号和括号改一个字段要找半天用 YAML 写层级一目了然还能加注释说明每个字段是干嘛的。举个实际的对比。假设你要配置一个模型后端JSON 大概长这样{ provider: local, endpoint: http://localhost:1234/v1, model: qwen2.5-coder, timeout: 60, retry: { max: 3, backoff: 2 } }同样的东西用 YAMLprovider: local endpoint: http://localhost:1234/v1 model: qwen2.5-coder timeout: 60 retry: max: 3 backoff: 2信息量一样但 YAML 版本你一眼就能扫完改timeout不用数括号。这就是为什么 openrig 这类“装配层”项目倾向于用 YAML——配置是给人看的不是给机器看的可读性优先。注意YAML 对缩进极其敏感绝对不能用 Tab 缩进必须用空格。我见过太多人复制粘贴配置后报“mapping values are not allowed here”九成是缩进里混了 Tab。建议编辑器统一设置“Tab 转 2 空格”。2.2 为什么运行时选 Node.js再说 Node.js。Claude Code 和 Codex 的 CLI 都是基于 Node.js 生态分发的这是绕不开的。你装 Claude Code 的时候本质上是npm install -g一个包Codex 的 CLI 同理。所以 Node.js 不是“可选项”而是“前置依赖”。但这里有个坑也是热搜里反复出现的问题Node.js 版本。热搜词里有“error installing 24.21.0: node.js v24.21.0 is not yet released”这就是典型的版本问题——你指定的版本号在官方源里根本不存在或者你的包管理器缓存了错误的版本索引。还有人问“node.js lts下载”“node.js官网下载”说明很多人连从哪装、装哪个版本都没搞清楚。我的建议很明确装 LTS 版本不要追最新的 Current 版本。LTS 是长期支持版稳定生态兼容性好。Claude Code 和 Codex 这类工具对 Node.js 版本有最低要求通常是 18 以上但没必要上最新的实验版本。截至我写这篇内容时Node.js 20 LTS 和 22 LTS 都是稳妥的选择。为什么强调版本因为 Node.js 的版本管理如果做不好会出现“全局装了一个版本项目里又要求另一个版本”的混乱。这时候nvmNode Version Manager就派上用场了。用 nvm 可以在同一台机器上管理多个 Node.js 版本按项目切换互不干扰。这是我在多项目环境下最推荐的方案。2.3 openrig 的“装配”逻辑分层解耦把 YAML 和 Node.js 放在一起看openrig 这类项目的设计逻辑就清晰了用 YAML 做配置层用 Node.js 做运行时层中间通过 CLI 工具做适配层。三层解耦各管各的。配置层YAML定义“用什么模型、连哪个 endpoint、走什么参数”。改配置不动代码。运行时层Node.js提供 CLI 工具运行的基础环境。版本对了工具就能跑。适配层Claude Code / Codex CLI把配置翻译成实际的 API 调用。这一层是工具自己实现的你只需要喂给它正确的配置。这种分层的好处是换模型不用重装工具换工具不用重写配置。比如你今天用 Claude Code 接官方模型明天想换成 Codex 接本地模型配置层改几行 YAML运行时层不动适配层换个 CLI 就行。这就是“rig”装配架这个词的精髓——架子搭好零件随便换。3. 核心细节解析YAML 配置、Node.js 环境与工具接入3.1 YAML 配置文件怎么写才不出错先解决最基础的问题YAML 文件怎么创建、放哪里。热搜里有人问“yolov10 yaml文件怎么创建”“rstudio的yaml在哪里”虽然场景不同但底层问题一样——YAML 文件的位置和命名是有约定的。对于 AI 编程工具的配置常见的约定是全局配置放在用户主目录下比如~/.claude/config.yaml或~/.codex/config.yaml。项目级配置放在项目根目录比如.openrig.yaml或.claude/settings.yaml。工具会按“项目级优先于全局级”的顺序合并配置。创建 YAML 文件本身很简单用任何文本编辑器新建一个.yaml或.yml后缀的文件即可。关键是内容格式。我总结几个新手最容易踩的坑常见错误报错信息正确做法用 Tab 缩进mapping values are not allowed here全部用空格统一 2 空格冒号后没空格could not find expected :key: value冒号后必须有空格字符串没加引号含特殊字符解析异常含:、#、{的值用引号包起来布尔值写成 yes/no被解析成字符串或报错用true/false多行字符串缩进错内容被截断用 一个完整的、能跑通的配置示例大概长这样# openrig 风格的多后端配置 version: 1 defaults: timeout: 60 retry: max: 3 backoff: 2 providers: local: type: openai-compatible endpoint: http://localhost:1234/v1 model: qwen2.5-coder api_key: not-needed remote: type: anthropic endpoint: https://api.anthropic.com model: claude-sonnet api_key: ${ANTHROPIC_API_KEY} tools: claude-code: provider: remote codex: provider: local这个配置里${ANTHROPIC_API_KEY}是环境变量引用不要把密钥硬编码进 YAML这是安全底线。工具在读取时会自动替换成环境变量的值。提示写完 YAML 后别急着跑工具先用一个 YAML 校验器过一遍。命令行里可以用python -c import yaml,sys; yaml.safe_load(open(config.yaml))快速验证语法。语法错了工具报的错往往很隐晦先排除语法问题能省一半排查时间。3.2 Node.js 环境搭建版本、安装与验证Node.js 的安装我分三种场景说你对号入座。场景一全新安装单版本够用。直接去 Node.js 官网下载 LTS 版本的安装包。Windows 下是.msimacOS 下是.pkgLinux 下建议用包管理器。装完之后验证node -v npm -v两条命令都能输出版本号说明装好了。如果node -v报“command not found”说明 PATH 没配好Windows 下重装时勾选“Add to PATH”Linux/macOS 下检查 shell 配置文件。场景二多版本共存需要切换。用 nvm。Linux/macOS 下curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重开终端后 nvm install 20 nvm use 20 nvm alias default 20Windows 下用 nvm-windows安装包直接搜“nvm-windows”下载。装完后nvm install 20、nvm use 20同理。场景三遇到版本报错。热搜里那个“node.js v24.21.0 is not yet released”就是典型。原因通常是你在package.json或某个配置里指定了一个不存在的版本号或者 nvm 的远程版本列表没更新。解决办法先nvm ls-remote看看有哪些可用版本选一个真实存在的 LTS 版本别手写一个想当然的版本号。Node.js 装好之后全局安装 CLI 工具npm install -g anthropic-ai/claude-code npm install -g openai/codex如果安装慢可以换国内镜像源npm config set registry https://registry.npmmirror.com装完验证claude --version codex --version能输出版本号说明 CLI 层通了。3.3 Claude Code 与 Codex 的接入配置工具装好了接下来是接入。Claude Code 和 Codex 的接入逻辑类似都是“读配置 → 找 provider → 发请求”。区别在于配置字段名和默认行为。Claude Code 的配置重点是provider和endpoint。如果你想接官方模型配置里填官方 endpoint 和 API key如果你想接本地模型比如 LM Studio 跑的endpoint 指向http://localhost:1234/v1模型名填你在 LM Studio 里加载的模型名。热搜里“claude code 调用 lmstudio 的本地模型”就是这个场景。Codex 的配置热搜里有个很具体的报错“cc switch local proxy failed while handling codex endpoint /responses”。这个报错的意思是代理层在处理 Codex 的/responses端点时失败了。常见原因是 endpoint 路径写错或者代理没正确转发。Codex 用的是/responses而不是/chat/completions如果你接的是 OpenAI 兼容接口要确认对方支持这个端点。很多本地模型服务默认只实现了/chat/completions这时候要么换支持/responses的服务要么在中间加一层适配。还有一个高频报错“codex is ignoring 1 unrecognized configuration setting. check for typos”。这是配置字段名拼错了。Codex 对配置字段名很严格多一个字母少一个字母都会报这个。解决办法就是对照官方文档一个字段一个字段核对。我自己的习惯是配置字段名直接从官方示例里复制绝不手打手打必错。3.4 本地模型接入的关键参数接本地模型是很多人折腾 openrig 的核心诉求。这里的关键参数有三个endpoint、model、api_key。endpoint本地模型服务的地址。LM Studio 默认是http://localhost:1234/v1Ollama 默认是http://localhost:11434/v1。注意/v1后缀很多 OpenAI 兼容服务都需要它。model模型名称必须和服务里加载的模型名完全一致。大小写敏感。你在 LM Studio 里加载的是qwen2.5-coder-7b配置里就得写qwen2.5-coder-7b写成Qwen2.5-Coder可能就找不到。api_key本地服务通常不校验但有些工具要求这个字段非空填个not-needed或任意字符串即可。一个实测能跑通的本地接入配置provider: local endpoint: http://localhost:1234/v1 model: qwen2.5-coder-7b api_key: not-needed timeout: 120timeout我特意调大到 120 秒因为本地模型首次加载和推理速度比云端慢默认 60 秒经常超时。这是踩过坑之后的经验值。4. 实操过程从零搭一套可用的 openrig 工作流4.1 环境准备与依赖安装的完整顺序我把整个流程按顺序列一遍你照着做就行。顺序很重要先装 Node.js再装 CLI 工具最后写配置颠倒顺序会出各种奇怪问题。第一步装 Node.js LTS。用 nvm 装 20 版本设默认。第二步配 npm 镜像源国内网络环境建议做。第三步全局装 Claude Code 和 Codex CLI。第四步验证两个 CLI 都能输出版本号。第五步创建配置目录和 YAML 文件。第六步填入 provider 配置先接一个最简单的后端测试。第七步跑一个最小任务验证链路通不通。这个顺序的逻辑是每一层都验证通过再进下一层。很多人一上来就把所有配置写完结果报错不知道是哪一层的问题。分层验证报错定位快得多。4.2 配置文件的组织与参数计算配置文件的组织我推荐“全局默认 项目覆盖”的结构。全局配置放通用设置超时、重试、默认 provider项目配置放项目特有的东西项目上下文文件、特定模型。参数计算这块重点说timeout和retry。timeout怎么定看你的模型响应速度。云端模型通常 30-60 秒够用本地模型建议 120 秒起步。如果你用的是参数量大的本地模型比如 30B 以上跑在消费级显卡上首次推理可能要几分钟timeout得设到 300 秒。retry的backoff怎么算指数退避。max: 3、backoff: 2的意思是第一次失败等 2 秒第二次等 4 秒第三次等 8 秒。这个设置适合网络抖动场景。如果是对端限流rate limit退避时间要更长backoff设到 5 甚至 10。retry: max: 3 backoff: 2 # 实际等待序列2s, 4s, 8s4.3 跑通第一个任务的现场记录配置写好后跑一个最小任务验证。我用 Claude Code 举例claude 用一句话解释什么是递归如果配置正确你会看到模型返回一句话。如果报错按下面的顺序排查claude --version能不能输出不能是安装问题。配置文件路径对不对工具默认读的路径和你放的位置是否一致。endpoint 通不通用curl直接打一下 endpoint。API key 有没有正确注入环境变量有没有 export。curl测试 endpoint 的命令curl http://localhost:1234/v1/models能返回模型列表说明本地服务正常。返回连接拒绝说明服务没起来。这一步的现场记录很关键。我第一次接本地模型时claude一直报连接超时curl却正常。后来发现是配置文件里 endpoint 写成了http://127.0.0.1:1234/v1而工具解析时对127.0.0.1和localhost的处理不一致换成localhost就好了。这种坑不实际跑一遍根本想不到。4.4 多工具切换的配置技巧openrig 的核心价值之一是“切换”。你可能有多个工具Claude Code、Codex多个后端官方、本地、第三方。切换的关键是把 provider 抽象出来工具只引用 provider 名。providers: fast: endpoint: http://localhost:1234/v1 model: qwen2.5-coder-7b strong: endpoint: https://api.anthropic.com model: claude-sonnet tools: claude-code: provider: strong codex: provider: fast这样切换时只改provider字段不用动 endpoint 和 model。想临时切换可以用环境变量覆盖OPENRIG_PROVIDERfast claude 帮我写个排序函数这种“配置 环境变量覆盖”的模式是我在多后端环境里最常用的技巧。临时切一下不用改文件跑完就恢复。5. 常见问题与排查技巧实录5.1 安装类问题速查安装阶段的问题我整理成一张表对照排查报错关键词根本原因解决办法node.js vXX is not yet released版本号不存在nvm ls-remote查真实版本command not found: nodePATH 未配置重装勾选 Add to PATHnpm install 卡住网络问题换镜像源 registry.npmmirror.comEACCES permission denied权限不足别用 sudo改用 nvm 管理claude: command not found全局包未装或 PATH 问题重装npm i -g检查 npm 全局路径“EACCES permission denied”这个坑特别典型。很多人第一反应是加sudo结果装出来的包权限混乱后面更难处理。正确做法是用 nvm 管理 Node.jsnvm 装的 Node.js 在用户目录下全局包也装在用户目录根本不需要 sudo。5.2 配置类问题排查思路配置类问题核心排查思路是“先验证语法再验证字段最后验证连通性”。语法问题用 YAML 校验器。字段问题对照官方文档。连通性问题用curl。热搜里“codex is ignoring 1 unrecognized configuration setting”就是字段问题。Codex 的配置字段名和 Claude Code 不完全一样别混用。比如 Claude Code 用modelCodex 可能用model_name或别的。每个工具的配置字段以该工具官方文档为准不要想当然地套用。还有一个隐蔽的坑配置文件的编码。YAML 文件必须是 UTF-8 无 BOM 编码。Windows 下用记事本保存有时会带 BOM导致解析失败。用 VS Code 保存时注意右下角的编码显示选“UTF-8”而不是“UTF-8 with BOM”。5.3 模型接入类问题实录模型接入的问题最典型的是“endpoint 路径不对”和“模型名不匹配”。endpoint 路径OpenAI 兼容接口的标准路径是/v1/chat/completions但配置里通常只写到/v1工具会自动补全后面的部分。如果你写全了反而可能变成/v1/chat/completions/chat/completions报 404。配置里只写到/v1为止。模型名必须和服务端加载的模型名完全一致。LM Studio 里显示的模型名复制粘贴到配置里别手打。我见过有人把qwen2.5-coder打成qwen2.5-coder中间多了个空格排查了半天。“cc switch local proxy failed while handling codex endpoint /responses”这个报错本质是代理层和 Codex 的端点约定不一致。Codex 用/responses如果你的代理只转发了/chat/completions就会失败。解决办法是确认代理支持/responses或者换一个支持该端点的本地服务。5.4 独家避坑经验分享几个我踩过、但文档里不会写的坑。坑一环境变量没生效。你在.bashrc里 export 了 API key但工具是在另一个 shell 会话里跑的读不到。解决办法确认工具运行的环境和 export 的环境是同一个或者把 key 写进工具的配置文件注意文件权限设为 600。坑二端口被占用。本地模型服务默认端口 1234如果你同时跑了别的服务占了这个端口模型服务起不来但报错信息可能很隐晦。用lsof -i :1234Linux/macOS或netstat -ano | findstr 1234Windows查端口占用。坑三配置文件优先级搞混。全局配置和项目配置同时存在时项目配置覆盖全局配置。但有些工具是“合并”而不是“覆盖”字段级别的合并逻辑要搞清楚。我建议全局配置只放通用项项目配置放差异项减少合并歧义。坑四Node.js 版本和工具不兼容。有些工具要求 Node.js 18有些要求 20。装之前先看工具的package.json里的engines字段或者官方文档的“Prerequisites”。版本不对装上了也跑不起来。6. 工具选型与扩展openrig 思路还能怎么用6.1 Claude Code 与 Codex 的选型对比这两个工具我都用说说差异。Claude Code 的强项是上下文理解和代码生成质量接官方模型时体验很顺。Codex 的强项是和 OpenAI 生态的集成配置风格偏 OpenAI 那套。维度Claude CodeCodex配置风格YAML字段偏 AnthropicYAML/JSON字段偏 OpenAI默认端点Anthropic APIOpenAI API本地模型接入支持需 OpenAI 兼容层支持注意/responses端点适合场景复杂代码理解、重构快速生成、OpenAI 生态集成选型建议如果你主要用 Anthropic 的模型选 Claude Code如果你在 OpenAI 生态里或者要接很多 OpenAI 兼容的本地模型Codex 更顺。当然用 openrig 的思路两个都装、按需切换才是最灵活的。6.2 把 openrig 思路扩展到更多工具openrig 的分层思路不局限于这两个工具。任何“配置 CLI 模型后端”的组合都能套这个架子。比如你用的是别的 AI 编程助手只要它支持自定义 endpoint 和模型就能纳入同一套 YAML 配置管理。扩展的关键是抽象出统一的 provider 定义。不管底层是 Anthropic、OpenAI 还是本地服务在配置层都抽象成provider工具层只引用 provider 名。这样新增一个后端只需要在providers里加一段不用改工具配置。providers: anthropic: type: anthropic endpoint: https://api.anthropic.com openai: type: openai endpoint: https://api.openai.com/v1 local-lmstudio: type: openai-compatible endpoint: http://localhost:1234/v1 local-ollama: type: openai-compatible endpoint: http://localhost:11434/v1这种“一个架子多个后端”的模式就是 openrig 这个名字最实在的价值。6.3 版本管理与配置备份的实操建议最后说两个运维层面的建议。版本管理把 openrig 的配置文件纳入 Git 管理。但密钥绝对不能进 Git。用环境变量引用配置文件里只写${VAR_NAME}。再配一个.gitignore排除本地的密钥文件。配置备份配置文件改坏了想回滚有 Git 就方便。我习惯每次大改配置前先 commit 一次改坏了git checkout就回来了。这个习惯帮我省过好几次重配环境的时间。多机同步如果你在多台机器上用同一套配置把配置文件放 Git 仓库各机器 clone 下来环境变量各自设置。这样配置一致密钥隔离安全又方便。我在实际使用中最大的体会是AI 编程工具的“装配”比“使用”更花时间。模型能力都差不多真正拉开效率差距的是你的配置管理是否清晰、切换是否顺畅、报错是否能快速定位。openrig 这类思路的价值不在于它有多复杂而在于它把混乱的配置收敛成了一套可维护的结构。把 YAML 写规范把 Node.js 环境管好把 provider 抽象出来剩下的就是享受“换个模型继续干活”的顺畅感了。