1. 从 openrig 这个名字说起：它到底想解决什么问题
第一次看到 openrig 这个项目名，我脑子里冒出来的第一反应是"open"加"rig"的组合。rig 在工程语境里通常指"装配好的成套设备"，比如一台调试完毕的工作站、一套搭好的测试台架。放到 AI 编程工具这个圈子里，openrig 想做的事情就很清楚了：把散落一地的命令行 AI 助手、模型接口、配置文件和本地环境，装配成一套开箱即用的统一工作台。
我接触过太多人在配置 Claude Code、Codex 这类工具时卡在同一个地方：Node.js 版本不对、YAML 配置文件写错缩进、本地模型接口连不上、代理转发报错。这些问题的共同点是，它们跟"用 AI 写代码"这件事本身毫无关系，纯粹是环境装配的脏活。openrig 的价值就在于把这堆脏活收敛成一套可复现的配置骨架，让你把精力放回真正重要的地方。
这篇文章适合三类人看。第一类是刚听说 Claude Code、Codex，想上手但被安装步骤劝退的新手；第二类是已经装好了但经常遇到配置报错、想搞明白底层逻辑的进阶用户；第三类是想把多个模型后端（本地模型、第三方 API）统一管理起来的老手。我会从整体设计思路讲到具体配置细节，再把我踩过的坑一个个摊开说，尽量让你少走弯路。
需要先说明一点，openrig 这类项目本质上是一层"编排层"，它不生产模型能力，而是把已有的工具和接口组织起来。理解这一点很关键，因为后面所有的配置逻辑，都是围绕"如何让不同组件正确对话"展开的。
2. 整体设计思路：为什么是 YAML + Node.js 这套组合
2.1 编排层的核心矛盾：灵活性与可复现性的平衡
任何一套工具编排方案都要面对一对矛盾：配置越灵活，能适配的场景越多，但复现难度也越高；配置越死板，越容易一键跑通，但换个环境就歇菜。openrig 选择用 YAML 作为配置载体，本质上是在这对矛盾里找了一个偏"可读可改"的平衡点。
YAML 最大的好处是人能直接看懂。相比 JSON，它没有那么多括号和引号，缩进即层级，写起来接近自然语言。你打开一个 openrig 的配置文件，基本能一眼看出哪个字段对应哪个模型、哪个参数控制哪个行为。这对需要频繁调整模型后端的人来说太重要了——你不需要记语法，改一个值就行。
但 YAML 的坑也恰恰在缩进上。它用空格数量表达层级关系，多一个少一个空格，整个结构就变了。我见过太多人因为把两个空格写成四个，导致配置解析失败却完全看不出问题在哪。所以用 YAML 的第一条铁律是：统一用空格，绝不用 Tab，缩进层级固定为 2 个空格。这条规则听起来简单，但能帮你省下大量排查时间。
2.2 为什么底层运行时选 Node.js
Claude Code、Codex CLI 这类工具绝大多数是基于 Node.js 生态分发的。它们通过 npm 安装，运行时依赖 Node 的解释器。这就决定了你想用这些工具，Node.js 是绕不过去的前置条件。
选 Node.js 还有一层现实考虑：它的跨平台一致性做得不错。同一套 npm 包，在 Windows、macOS、Linux 上安装命令基本一致，行为差异也被控制在可接受范围内。对于 openrig 这种想做到"一套配置多端复用"的项目来说，这是刚需。
不过 Node.js 的版本管理是个大坑。不同工具对 Node 版本的要求不一样，有的要 18+，有的明确要 20+，还有的在新版本上反而出问题。我后面会专门讲版本管理这块怎么处理，这里先记住一个结论：别用系统自带的 Node，用版本管理工具装。
2.3 组件之间的对话关系
把 openrig 拆开看，它其实在协调三方对话：前端是 Claude Code 或 Codex 这类客户端，中间是配置和转发层，后端是真正的模型服务（可能是本地跑的模型，也可能是第三方 API）。
客户端负责接收你的指令、组织上下文、发起请求；配置层决定请求发给谁、带什么参数；模型服务负责真正生成内容。openrig 要做的就是让这三方各司其职又无缝衔接。理解了这条链路，后面遇到任何报错，你都能快速定位是哪一环出了问题——是客户端没起来，还是配置写错了，还是后端连不上。
3. 环境准备：Node.js 与包管理器的正确打开方式
3.1 Node.js 版本选择与安装路径
前面说了别用系统自带 Node，那用什么？我的建议是用 nvm（Node Version Manager）或者它的 Windows 对应版本。nvm 能让你在同一台机器上装多个 Node 版本，随时切换，互不干扰。
安装 nvm 之后，装 Node 20 LTS 是个稳妥选择。为什么是 20 而不是最新的 24？因为很多 AI 编程工具在 20 上验证得最充分，而更新的版本偶尔会遇到兼容性问题。我实测下来，Node 20 的 LTS 版本在 Claude Code 和 Codex 上都没出过幺蛾子。
具体操作上，Linux 和 macOS 用户装完 nvm 后执行：
nvm install 20 nvm use 20 nvm alias default 20最后那行nvm alias default 20很关键，它把 20 设为默认版本，这样你新开终端时不会莫名其妙回到旧版本。Windows 用户用 nvm-windows，命令类似，但要注意安装时它会问你要不要接管已有的 Node，选是。
装完之后验证一下：
node -v npm -v两个命令都要能正常输出版本号。如果node -v报"command not found"，多半是环境变量没配好，重启终端或者手动把 nvm 的路径加进 PATH。
注意：如果你之前用系统包管理器装过 Node，装 nvm 前最好先卸载干净，否则两套 Node 会打架，出现"明明装了 20 却还是跑旧版本"的诡异现象。
3.2 包管理器：npm、pnpm 还是 yarn
npm 是 Node 自带的，够用但慢。pnpm 用硬链接共享依赖，装得快、占空间小，现在很多新项目默认用它。yarn 介于两者之间。
对 openrig 这类工具编排场景，我推荐 pnpm。原因很简单：你可能会同时装 Claude Code、Codex 以及一堆辅助工具，它们之间有大量重复依赖，pnpm 能显著减少磁盘占用和安装时间。装 pnpm 的命令：
npm install -g pnpm装完之后，后续所有全局工具都可以用pnpm add -g来装。不过要注意，有些工具的安装脚本对 npm 有硬依赖，遇到装不上的情况，退回 npm 试试往往能解决。
3.3 全局安装目录的权限问题
在 Linux 和 macOS 上，全局安装 npm 包经常遇到权限报错，提示你没有权限写入/usr/local/lib/node_modules。很多人第一反应是加sudo，这是个坏习惯——用 sudo 装的包，后续普通用户身份运行时可能读不到配置，还会污染系统目录。
正确做法是给 npm 配置一个用户级的全局目录：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加进 PATH。这样你装的所有全局工具都在自己家目录下，不需要任何特殊权限，卸载也干净。
4. 配置文件详解：YAML 怎么写才不出错
4.1 YAML 基础语法与常见陷阱
YAML 的语法看着简单，但细节多。我先把最容易踩的几个坑列出来，这些是我在实际配置中反复遇到的：
第一，缩进只能用空格。Tab 字符在 YAML 里是非法缩进，解析器会直接报错。很多编辑器默认 Tab 键插入的是 Tab 字符，你得在设置里改成"插入空格"。
第二，冒号后面必须跟空格。key:value是错的，key: value才对。这个错误特别隐蔽，因为有些解析器能容忍，有些直接崩。
第三，字符串里的特殊字符要引号包裹。比如值里包含冒号、井号、大括号，最好用引号括起来，避免被误解析。
第四，列表项的短横线后面要有空格。-item是错的，- item才对。
我建议你写完 YAML 后，用一个在线校验工具或者编辑器插件先检查一遍。VS Code 装个 YAML 插件，它会实时标红语法错误，比事后排查省事得多。
4.2 一个典型的 openrig 配置结构
下面是一个我常用的配置骨架，你可以照着改：
version: 1 defaults: provider: local timeout: 60 providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 model: local-model remote: type: openai-compatible base_url: https://api.example.com/v1 model: remote-model api_key_env: MY_API_KEY tools: claude-code: provider: local extra_args: - --verbose codex: provider: remote这个结构分三层：defaults定义全局默认值，providers定义各个模型后端，tools定义每个工具用哪个后端。这样设计的好处是，你想换后端时只改tools里的一行，不用动其他配置。
api_key_env这个字段值得说一下。它不直接写密钥，而是写一个环境变量的名字，运行时从环境变量里读。这样做是为了避免密钥被提交到代码仓库。密钥这种东西，永远不要硬编码在配置文件里。
4.3 配置校验与热加载
配置写完不是终点，你得验证它真的生效了。大多数工具支持一个--config参数指定配置文件路径，也支持--dry-run之类的选项做校验。我习惯先用校验模式跑一遍，确认没语法错误再正式启动。
热加载这块，不同工具支持程度不一样。有的改了配置要重启进程，有的能自动重载。如果你不确定，最保险的做法是改完配置重启一次。别嫌麻烦，重启一次几秒钟，比对着一个不生效的配置排查半天强。
提示：把配置文件纳入版本管理时，记得用
.gitignore排除掉含密钥的本地覆盖文件。常见做法是提交一个config.example.yaml作为模板，真正的config.yaml留在本地。
5. 实操过程：从零搭起一套可用的工作台
5.1 安装 Claude Code 与 Codex
环境准备好之后，装工具本身。Claude Code 和 Codex 都是通过 npm 全局安装的，命令大致是：
pnpm add -g @anthropic-ai/claude-code pnpm add -g @openai/codex包名可能随版本变化，装之前最好去官方文档确认一下当前的正确包名。装完之后，用claude --version和codex --version验证是否安装成功。
如果安装过程中报错，最常见的原因是 Node 版本不匹配。回到第 3 节，确认你用的是 20 LTS。另一个常见原因是网络问题导致包下载不完整，重试一次或者换个镜像源通常能解决。
5.2 接入本地模型：以 LM Studio 为例
很多人想用本地模型跑 Claude Code，图的是数据不出本机、不花钱。LM Studio 是个不错的选择，它能在本地起一个兼容 OpenAI 接口的服务。
操作步骤是这样的：先在 LM Studio 里加载一个模型，然后在它的开发者选项里启动本地服务器，默认端口通常是 1234。启动后你会得到一个http://127.0.0.1:1234/v1这样的地址。
接下来在 openrig 配置里，把 provider 的base_url指向这个地址，type设为openai-compatible。因为 LM Studio 暴露的就是 OpenAI 兼容接口，所以任何支持 OpenAI 协议的客户端都能直接连。
这里有个细节要注意：本地模型的上下文窗口通常比云端模型小。如果你的对话很长，可能会遇到"超出上下文长度"的报错。解决办法是在配置里限制历史消息条数，或者换一个上下文窗口更大的模型。
5.3 接入第三方 API 的配置要点
如果你用的是第三方 API 服务，配置逻辑类似，区别主要在base_url和认证方式。大多数服务用 Bearer Token 认证，你需要在配置里指定从哪个环境变量读密钥。
设置环境变量的方式，Linux 和 macOS 是在 shell 配置文件里加一行：
export MY_API_KEY="your-key-here"Windows 用户可以在系统设置里配，或者用 PowerShell 的$env:MY_API_KEY="..."临时设置。改完环境变量记得重开终端，否则当前会话读不到新值。
第三方 API 还有个坑是模型名称。不同服务商对同一个模型的命名可能不一样，配置里的model字段必须跟服务商文档里写的完全一致，差一个字符都会报"模型不存在"。
5.4 在 VS Code 里集成
如果你习惯在 VS Code 里写代码，可以装 Claude Code 的 VS Code 扩展，这样不用切终端就能调用。装完扩展后，它通常会读取你已有的配置文件，或者让你在设置里指定配置路径。
集成之后的好处是，AI 能直接看到你当前打开的文件和选中的代码，上下文更精准。但要注意，扩展和命令行工具可能读的是不同的配置文件，改配置时两边都要照顾到，否则会出现"命令行能用、扩展不能用"的情况。
6. 常见报错与排查技巧实录
6.1 代理转发类报错
有一类报错特别典型，大意是"处理某个端点时本地代理失败"。这类问题的根源通常是中间转发层没起来，或者转发规则配错了。
排查思路是这样的：先确认转发服务本身在不在跑，用curl直接打一下它的健康检查接口。如果服务没起来，看它的日志找原因；如果服务起来了但转发失败，检查转发规则里的目标地址和端口对不对。
我遇到过一次，转发服务配置里写的目标端口是 8080，但实际后端监听的是 1234，结果所有请求都打到空气上。这种错误没有任何技术含量，但排查起来很费时间，因为报错信息不会直接告诉你"端口写错了"。所以我的经验是，配置里的每一个地址和端口，都要跟实际服务核对一遍。
6.2 模型不支持类报错
另一类常见报错是"某某模型不被支持"。这通常发生在你配置里写的模型名，跟后端实际提供的模型对不上。可能是拼写错误，也可能是后端根本没加载这个模型。
解决办法很直接：列出后端实际可用的模型列表，然后从里面挑一个填进配置。大多数兼容 OpenAI 接口的服务都提供/v1/models端点，curl一下就能看到全部可用模型。
6.3 配置被忽略类报错
还有一种报错提示"忽略了某个无法识别的配置项"。这多半是配置字段名拼错了，或者用了当前版本不支持的字段。YAML 对字段名大小写敏感，baseUrl和base_url是两个完全不同的东西。
遇到这类报错，先对照官方文档确认字段名的正确写法，再检查缩进层级对不对。有时候字段名没错，但缩进错了，导致它被解析到了错误的层级下，也会被当成"无法识别"。
6.4 常见问题速查表
| 报错关键词 | 可能原因 | 排查方向 |
|---|---|---|
| 代理失败 | 转发服务未启动或规则错误 | 检查服务状态与目标地址端口 |
| 模型不支持 | 模型名拼写错误或后端未加载 | 列出后端可用模型核对 |
| 配置被忽略 | 字段名拼写或缩进层级错误 | 对照文档检查字段与缩进 |
| 权限不足 | 全局目录权限问题 | 配置用户级全局目录 |
| 版本不匹配 | Node 版本不符合要求 | 切换到 20 LTS |
6.5 我踩过的几个坑
第一个坑是环境变量没生效。我在 shell 配置文件里加了export，但当前终端是之前开的，读不到新变量，折腾了半天才发现要重开终端。这个坑现在想起来还觉得蠢，但确实很多人会犯。
第二个坑是配置文件路径。有些工具默认读当前目录下的配置，有些读用户家目录下的，还有些读环境变量指定的路径。你不确定的时候，用工具的--help看看它支持哪些指定配置的方式，别想当然。
第三个坑是多个工具抢同一个端口。我同时跑本地模型服务和另一个开发服务器，两个都想用 1234 端口，结果后启动的那个起不来。解决办法是给其中一个换端口，配置里同步改掉。
7. 进阶玩法：多后端切换与统一管理
7.1 用配置切换不同模型后端
openrig 这类编排方案最实用的地方，是让你能在多个后端之间快速切换。比如白天用云端 API 图快，晚上用本地模型图省钱，切换只需要改配置里的一行。
我的做法是在配置里定义好几个 provider，然后给每个工具指定默认用哪个。想临时切换时，用命令行参数覆盖，比如--provider remote。这样既保留了默认配置的稳定性，又给了临时调整的灵活性。
7.2 密钥与敏感信息的管理
前面提过密钥不要硬编码，这里展开说下具体做法。最基础的是用环境变量，进阶一点可以用专门的密钥管理工具，或者用系统的密钥链。
环境变量方案的局限是，它在你重启终端后会丢失（除非写进 shell 配置文件）。写进 shell 配置文件又有个问题：所有在这个 shell 里跑的程序都能读到你的密钥。如果你对安全性要求高，可以考虑用密钥管理工具，按需注入。
7.3 配置的版本化与团队共享
如果你想把配置分享给团队，关键是分离"通用配置"和"个人配置"。通用部分（provider 定义、工具参数）提交到仓库，个人部分（密钥、本地路径）留在本地，通过一个config.local.yaml之类的文件覆盖。
大多数配置系统支持多文件合并，后面的文件覆盖前面的。你可以让主配置定义骨架，本地配置只写差异部分。这样团队共享时，每个人拉下来改改本地配置就能用，不用动主配置。
8. 一些实操心得
配置这套东西，最忌讳的是"一把梭"。我见过有人把所有配置堆在一个文件里，改一处牵动全身，出问题根本不知道是哪改坏的。我的建议是分层管理：环境相关的、工具相关的、密钥相关的分开，每层只关心自己的事。
另一个心得是，每次改配置只改一个地方，改完立刻验证。这样一旦出问题，你马上知道是刚才那处改动导致的。如果一次改五处，报错了你得挨个回滚排查，效率极低。
还有一点，把常用的排查命令记下来，做成一个小抄。比如查看端口占用、列出可用模型、检查环境变量，这些命令用熟了，排查速度能快好几倍。工具是死的，人是活的，把工具用顺手了，它才真正为你所用。
最后说个心态问题。配置环境这件事，第一次做肯定磕磕绊绊，报错一个接一个。但你要知道，这些坑是有尽头的，踩完一遍之后，下次换机器、换系统，你基本能凭肌肉记忆搞定。真正值钱的不是那几行配置，而是你在这个过程中建立起来的对整条链路的理解。理解了链路，任何报错你都能顺藤摸瓜找到根因，这才是最核心的能力。
