1. 从 openrig 这个名字说起：它到底想解决什么问题
第一次看到 openrig 这个标题，我脑子里冒出来的第一个念头是“又一个把 CLI 工具包装成图形界面的壳子”。但把热词列表扫了一遍之后，我意识到它踩中的其实是一个很具体的痛点：Claude Code、Codex 这类命令行 AI 编程助手，功能确实强，但配置过程对普通开发者来说门槛不低。你要装 Node.js、要处理 YAML 配置文件、要切换不同的模型端点、还要在 VS Code 里把它们串起来。openrig 想做的事情，本质上就是把这些零散的配置环节收拢到一个统一的框架里，让“装好就能用”这件事变得不那么折腾。
我个人的判断是，openrig 的核心价值不在于它发明了什么新技术，而在于它把 Claude Code、Codex、YAML 配置、Node.js 运行时这几样东西的集成路径给标准化了。你可以把它理解成一个“脚手架”或者“装配台”——它不生产模型，也不生产编辑器，它做的是把模型接入编辑器这条链路上的每一个环节都定义清楚，让你不用每次都从头查文档、试参数、踩版本坑。
适合读这篇内容的人大概分三类。第一类是刚接触 Claude Code 或 Codex、被安装配置卡住的开发者，你可能已经看过官方文档但还是在某个环节报错。第二类是已经在用这些工具、但想把自己的配置流程整理得更规范的人，比如你手头有好几台机器、好几个项目，每次都要重新配一遍。第三类是对 YAML 配置和 Node.js 工具链不太熟悉、但想借这个机会把基础打牢的人。不管你是哪一类，下面的内容都会从实际操作的视角出发，把每个环节的“为什么”和“怎么做”讲清楚。
2. 整体设计思路：为什么是 YAML + Node.js + CLI 这套组合
2.1 为什么配置层选 YAML 而不是 JSON 或 TOML
openrig 这类工具选择 YAML 作为配置格式，背后有很实际的考量。JSON 的问题是写起来太啰嗦，一个简单的模型端点配置要写一堆花括号和引号，而且 JSON 不支持注释，你没法在配置文件里标注“这行是给本地模型用的”或者“这个 key 下个月过期”。TOML 虽然比 JSON 友好，但嵌套结构表达起来不如 YAML 直观，尤其是当你需要配置多个模型提供商、每个提供商下面又有多个端点的时候，TOML 的层级会变得很别扭。
YAML 的优势在于它用缩进表达层级，视觉上更接近人类阅读配置时的思维习惯。比如你要配置一个 Claude Code 的模型端点，YAML 里大概长这样：
providers: - name: claude-code type: anthropic endpoint: https://api.anthropic.com/v1/messages model: claude-sonnet-4-20250514 api_key_env: ANTHROPIC_API_KEY - name: codex-local type: openai-compatible endpoint: http://localhost:1234/v1 model: local-model这种结构一眼就能看出层级关系，而且api_key_env这种字段名本身就带自解释性。但 YAML 也有它的坑，最大的问题就是缩进敏感——多一个空格少一个空格，解析结果可能完全不同。我在实际配置中遇到过好几次因为 tab 和空格混用导致解析失败的情况，后面会专门讲怎么排查这类问题。
2.2 Node.js 在整条链路里扮演什么角色
很多人会问“我就想用个 AI 编程助手，为什么非要装 Node.js”。这个问题的答案取决于你用的工具是怎么分发的。Claude Code 和 Codex 的 CLI 版本目前主要通过 npm 包的形式分发，而 npm 是 Node.js 的包管理器。也就是说，Node.js 在这条链路里扮演的是“运行时环境”的角色，它负责把 CLI 工具跑起来。
你可以把 Node.js 理解成 Java 的 JVM 或者 Python 的解释器。没有它，npm 包就没法执行。但这里有个常见的误区：很多人以为要装最新版的 Node.js 才行，实际上 Claude Code 和 Codex 对 Node.js 版本的要求通常是“LTS 版本及以上”。LTS 是长期支持版的意思，稳定性比最新版好，不会因为 Node.js 本身的小版本更新导致 CLI 工具突然跑不起来。
我在三台机器上分别用 Node.js 20 LTS、22 LTS 和 24 测试过，20 和 22 都没问题，24 在某些 npm 包的依赖解析上会报not yet released or is not available这类错误。所以我的建议是：如果你不是非要追新，装 22 LTS 就够了，没必要上 24。
2.3 openrig 的“装配台”思路解决了什么
在没有 openrig 这类工具之前，配置 Claude Code 或 Codex 的流程大概是这样的：先装 Node.js，然后用 npm 全局安装 CLI 工具，接着手动创建配置文件，再设置环境变量，最后在 VS Code 里装对应的扩展并指向 CLI 的路径。每一步都可能出错，而且出错之后的报错信息往往不指向根因。
openrig 的思路是把这些步骤收敛到一个配置文件里，你只需要维护一份 YAML，剩下的路径解析、环境变量注入、端点切换都由工具来处理。这个思路的好处是“配置即文档”——你打开 YAML 文件就能看到当前系统里所有模型端点的配置，不用去翻环境变量或者 npm 的全局配置。
但这里有个前提：openrig 本身也需要一个运行环境。如果它也是 npm 包，那 Node.js 还是绕不开。所以整个链路的依赖关系是：Node.js → openrig → Claude Code / Codex CLI → VS Code 扩展。理解这个依赖链很重要，因为当某个环节出问题时，你需要知道该从哪一层开始排查。
3. 核心细节解析：从安装到跑通的每个关键环节
3.1 Node.js 安装：版本选择和安装方式
Node.js 的安装方式主要有三种：官网下载安装包、用包管理器安装、用版本管理工具安装。我分别说一下适用场景。
官网下载安装包是最直接的方式，适合 Windows 用户或者不想折腾命令行的 Mac 用户。去 Node.js 官网下载 LTS 版本的安装包，双击下一步就行。但这种方式的问题是版本切换不方便，如果你以后需要同时维护多个 Node.js 版本的项目，就得卸载重装。
用包管理器安装适合 Mac 和 Linux 用户。Mac 上用 Homebrew 的话就是brew install node@22，Ubuntu 上用 apt 的话需要先加 NodeSource 的源再安装。这种方式的好处是升级方便，坏处是系统级的 Node.js 版本会被所有项目共享，遇到版本冲突时比较麻烦。
用版本管理工具安装是我最推荐的方式。Mac 和 Linux 上用 nvm，Windows 上用 nvm-windows。装好之后你可以用nvm install 22装一个 22 LTS，然后用nvm use 22切换过去。这样不同项目可以用不同的 Node.js 版本，互不干扰。
注意：如果你之前用官网安装包装过 Node.js，再装 nvm 可能会冲突。建议先把原来的卸载干净，再装 nvm。
安装完成之后，用node -v和npm -v验证一下。如果两个命令都能输出版本号，说明安装成功。如果node -v有输出但npm -v报错，通常是 npm 的全局路径没配好，需要检查 PATH 环境变量。
3.2 Claude Code 和 Codex 的安装路径差异
Claude Code 和 Codex 虽然都是 CLI 工具，但安装方式略有不同。Claude Code 目前主要通过 npm 全局安装，命令是npm install -g @anthropic-ai/claude-code。Codex 的安装方式取决于你用的是哪个版本，如果是 OpenAI 官方的 Codex CLI，通常也是 npm 包；如果是社区维护的版本，可能需要从 GitHub 直接下载二进制文件。
这里有个实际经验：全局安装 npm 包时，如果遇到权限错误（比如EACCES或permission denied），不要直接用sudo安装。用sudo装全局包会导致后续升级和卸载时出现权限混乱。正确的做法是配置 npm 的全局目录到用户目录下，具体操作是：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH然后把最后那行 export 加到你的 shell 配置文件里（.bashrc、.zshrc或.profile），这样每次打开终端都会自动生效。
安装完成之后，用claude --version或codex --version验证。如果提示command not found，说明 npm 的全局 bin 目录不在 PATH 里，需要检查上一步的配置。
3.3 YAML 配置文件的结构设计
openrig 的 YAML 配置文件通常放在项目根目录或者用户主目录下的隐藏文件夹里。具体位置取决于工具的约定，但结构设计的原则是通用的。一个完整的配置文件应该包含以下几个部分：
version: 1 default_provider: claude-code providers: - name: claude-code type: anthropic endpoint: https://api.anthropic.com/v1/messages model: claude-sonnet-4-20250514 api_key_env: ANTHROPIC_API_KEY max_tokens: 8192 temperature: 0.7 - name: codex-deepseek type: openai-compatible endpoint: https://api.deepseek.com/v1 model: deepseek-chat api_key_env: DEEPSEEK_API_KEY max_tokens: 4096 - name: local-lmstudio type: openai-compatible endpoint: http://localhost:1234/v1 model: local-model api_key_env: LMSTUDIO_API_KEY routing: default: claude-code fallback: codex-deepseek local_first: false这个结构里，providers列表定义了所有可用的模型端点，routing部分定义了默认用哪个、失败时切换到哪个。api_key_env字段的设计很关键——它不直接存 API key，而是存环境变量的名字。这样做的好处是配置文件可以安全地提交到版本控制里，不会泄露密钥。
提示：YAML 对缩进非常敏感，建议统一用两个空格作为一级缩进，不要用 tab。大多数编辑器可以设置“tab 转空格”，建议打开这个选项。
3.4 环境变量与密钥管理
API key 的管理是配置环节里最容易出问题的地方。常见的错误包括：环境变量名拼错、环境变量没导出、shell 配置文件没重新加载。我建议的做法是在 shell 配置文件里统一管理：
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx" export DEEPSEEK_API_KEY="sk-xxxxxxxx" export LMSTUDIO_API_KEY="not-needed"改完之后执行source ~/.zshrc（或者对应的配置文件）让改动生效。验证环境变量是否生效可以用echo $ANTHROPIC_API_KEY，如果输出为空说明没配好。
对于本地模型（比如 LM Studio），API key 通常不是必需的，但有些工具会强制要求这个字段存在。这种情况下随便填一个非空字符串就行，比如not-needed。
3.5 VS Code 扩展的配置要点
VS Code 里配置 Claude Code 或 Codex 扩展时，最关键的是指定 CLI 的路径。如果你是用 npm 全局安装的，CLI 路径通常在~/.npm-global/bin/或者/usr/local/bin/下面。在 VS Code 的设置里搜索对应的扩展配置项，把路径填进去。
另一个容易忽略的点是终端环境。VS Code 的集成终端可能不会自动加载你的 shell 配置文件，导致环境变量在终端里可用但在扩展里不可用。解决办法是在 VS Code 的settings.json里配置terminal.integrated.env.osx或对应的平台配置，把需要的环境变量显式传进去。
4. 实操过程：从零到跑通的完整流程
4.1 环境准备与依赖安装
假设你是一台全新的 Ubuntu 机器，从零开始配置。第一步是装 Node.js。我推荐用 nvm 来管理：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22这几条命令做完之后，node -v应该输出v22.x.x。然后装 Claude Code：
npm install -g @anthropic-ai/claude-code装完之后验证：
claude --version如果这一步报command not found，检查npm config get prefix的输出，确保那个路径下的bin目录在 PATH 里。
4.2 openrig 配置文件的创建与初始化
在项目根目录下创建openrig.yaml，内容参考上一节的结构。创建之后可以用openrig validate命令（如果工具支持的话）来检查配置文件语法。如果不支持 validate 命令，可以用 Python 的 yaml 模块快速检查：
python3 -c "import yaml; yaml.safe_load(open('openrig.yaml'))"如果没有报错，说明 YAML 语法没问题。如果有报错，错误信息会指出具体哪一行有问题，通常是缩进或者冒号后面缺空格。
4.3 模型端点的接入与切换
配置多个模型端点的实际价值在于：你可以根据任务类型切换不同的模型。比如代码生成用 Claude，文本总结用本地模型，翻译用 DeepSeek。切换的方式通常有两种：改配置文件里的default_provider，或者用命令行参数临时指定。
我在实际使用中的做法是：把最常用的模型设为默认，然后在需要的时候用--provider参数临时切换。这样既不用频繁改配置文件，又能灵活应对不同任务。
对于本地模型（比如通过 LM Studio 跑的模型），需要注意端点的地址。LM Studio 默认监听http://localhost:1234/v1，但如果你在 Docker 容器里跑 openrig，localhost 指向的是容器内部而不是宿主机。这种情况下需要把端点地址改成宿主机的 IP 或者用host.docker.internal。
4.4 验证配置是否生效
配置完成之后，用最简单的命令验证整条链路是否通畅。比如让 Claude Code 执行一个简单的任务：
claude "print hello world in python"如果能看到模型返回的代码，说明 CLI 到模型的链路是通的。然后在 VS Code 里打开一个文件，用扩展的快捷键触发一次代码补全或对话，验证编辑器到 CLI 的链路也是通的。
两个链路都通了之后，再测试切换提供商的功能。把default_provider改成另一个，重新执行同样的命令，看是否返回了不同模型的结果。
5. 常见问题与排查技巧实录
5.1 安装阶段的典型报错
报错一：error installing 24.21.0: node.js v24.21.0 is not yet released or is not available
这个报错通常出现在你用 nvm 安装了一个还不存在的版本号，或者 npm 包的 engines 字段要求了一个尚未发布的 Node.js 版本。解决办法是改用 LTS 版本，比如nvm install 22。
报错二：EACCES: permission denied
这是 npm 全局安装时的权限问题。不要用sudo解决，而是配置 npm 的 prefix 到用户目录。具体操作参考 3.2 节。
报错三：command not found: claude
npm 全局 bin 目录不在 PATH 里。用npm config get prefix找到路径，然后把<prefix>/bin加到 PATH 里。
5.2 配置解析阶段的典型报错
报错：yaml.scanner.ScannerError: mapping values are not allowed here
这是 YAML 缩进或冒号使用的问题。最常见的原因是冒号后面没加空格，比如name:claude-code应该写成name: claude-code。另一个原因是同一层级里混用了 tab 和空格。
报错：could not find expected ':'
通常是因为某个键值对写成了列表项，或者缩进层级不对。建议用编辑器的 YAML 插件来高亮显示缩进层级。
5.3 运行时阶段的典型报错
报错：cc switch local proxy failed while handling codex endpoint /responses
这个报错说明本地代理在转发请求到 Codex 端点时失败了。排查思路是：先确认 Codex CLI 本身能不能独立运行，如果能，说明问题出在代理配置上；如果不能，说明 Codex 的安装或配置有问题。代理配置常见的问题是端点地址写错、端口被占用、或者环境变量没传进去。
报错：your organization has disabled claude subscription access for claude code
这个报错说明你的账号所属组织禁用了 Claude Code 的订阅访问。这不是配置问题，需要联系组织管理员或者换一个账号。
报错：the 'gpt-5.6-sol' model is not supported when using codex with a...
模型名称写错了，或者该模型不支持当前的接入方式。检查配置文件里的model字段，确保模型名称和提供商文档里的一致。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 |
|---|---|---|
command not found | PATH 未配置 | 检查 npm prefix 和 PATH |
| YAML 解析报错 | 缩进或冒号问题 | 用 Python yaml 模块验证 |
| 模型返回空 | API key 未生效 | echo $API_KEY验证 |
| 本地模型连不上 | 端点地址错误 | 确认 localhost 指向 |
| 扩展不生效 | VS Code 环境变量缺失 | 检查 settings.json |
| 切换提供商失败 | 配置文件未重载 | 重启 CLI 或编辑器 |
5.5 几个我踩过的坑
第一个坑是 YAML 里的布尔值。YAML 会把yes、no、on、off自动解析成布尔值，如果你本来想写字符串，就会出问题。比如model: no会被解析成false。解决办法是给这类值加引号：model: "no"。
第二个坑是环境变量的加载顺序。如果你在.zshrc里配了环境变量，但 VS Code 是从 Dock 启动的，它可能不会加载.zshrc。解决办法是从终端启动 VS Code，命令是code .。
第三个坑是 npm 包的版本冲突。如果你之前装过旧版本的 Claude Code，再装新版本时可能不会覆盖旧版本。解决办法是先npm uninstall -g旧版本，再装新版本。
第四个坑是本地模型的并发限制。LM Studio 默认只允许一个并发请求，如果你同时用 Claude Code 和 Codex 访问同一个本地端点，第二个请求会排队或失败。解决办法是在 LM Studio 的设置里调高并发数，或者给不同的工具配不同的本地端点。
6. 进阶配置：多模型路由与本地模型接入
6.1 多提供商路由策略的设计
当你配置了多个模型提供商之后，路由策略就变得很重要。openrig 这类工具通常支持几种路由模式：默认路由、故障转移路由、按任务类型路由。默认路由就是所有请求都走default_provider；故障转移路由是在默认提供商失败时自动切换到备用提供商；按任务类型路由是根据请求的内容自动选择最合适的模型。
我在实际使用中的配置是：默认走 Claude Code，故障转移走 DeepSeek，本地模型只在明确指定时使用。这样既能保证日常使用的质量，又能在网络不稳定时有备选方案，同时本地模型作为隐私敏感任务的选项。
6.2 本地模型接入的注意事项
本地模型接入最大的优势是数据不出本机，适合处理敏感代码或文档。但本地模型的性能和云端模型有差距，尤其是在代码生成任务上。我的建议是把本地模型用在文本总结、格式转换、简单问答这类任务上，复杂的代码生成还是用云端模型。
接入本地模型时需要注意端点的兼容性。LM Studio 和 Ollama 都提供 OpenAI 兼容的 API，但细节上可能有差异。比如 LM Studio 的/v1/chat/completions端点支持流式输出，但/v1/completions端点可能不支持。配置时需要确认工具用的是哪个端点。
6.3 配置文件的版本管理与团队协作
如果你在团队里推广这套配置，建议把openrig.yaml提交到版本控制里，但 API key 通过环境变量注入。这样新成员克隆仓库后只需要配好自己的环境变量就能跑起来。可以在仓库里放一个.env.example文件，列出所有需要的环境变量名，但不包含实际值。
对于团队协作场景，还可以在配置文件里加注释说明每个提供商的用途和限制。YAML 支持#注释，这个特性在团队协作时很有价值。
7. 一些实际使用中的体会
配置这套东西的过程中，我最大的体会是“版本锁定”的重要性。Node.js 的版本、npm 包的版本、CLI 工具的版本，任何一个环节的版本变了都可能导致整条链路跑不起来。我的做法是在项目文档里记录当前验证过的版本组合，升级时先在小范围测试。
另一个体会是“配置即代码”的思路确实能省很多事。以前我每换一台机器就要重新配一遍环境变量和 CLI 路径，现在只需要把 YAML 文件和 shell 配置同步过去就行。但前提是配置文件要写得足够清晰，字段命名要自解释，注释要到位。
最后分享一个小技巧：如果你在 VS Code 里用 Claude Code 扩展时遇到环境变量不生效的问题，可以在 VS Code 的settings.json里加这样一段：
"terminal.integrated.env.linux": { "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}", "DEEPSEEK_API_KEY": "${env:DEEPSEEK_API_KEY}" }这样 VS Code 的集成终端会继承你 shell 里的环境变量，扩展调用 CLI 时就能拿到正确的 key。这个配置在 Ubuntu 和 macOS 上都验证过，Windows 上把linux换成windows即可。
