1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，我下意识以为是某个硬件机架项目，毕竟 rig 在英文里常指设备支架、钻井平台这类实体结构。但把 openrig 和 Claude Code、Codex、YAML、Node.js 这几个词摆在一起，方向就清楚了——这是一个围绕 AI 编程助手做配置编排、环境搭建和模型接入的开源工具或配置方案集合。说白了，它解决的是"我手头有好几个 AI 编程工具，怎么让它们统一跑起来、统一管理配置"这件事。

我自己从去年开始就在折腾 Claude Code 和 Codex 这两套命令行工具，中间踩过的坑能写满一整页笔记。最开始是单独装 Claude Code，配好之后发现有些场景想换 Codex 试试，结果两套工具的配置文件格式不一样、环境变量互相打架、模型端点各管各的。后来想接入本地模型或者第三方 API，又是一堆 YAML 要改。openrig 这类项目的价值就在这儿：它把多工具、多模型、多环境的配置收敛到一套结构里，用 YAML 做声明式描述，用 Node.js 做运行时支撑，让你不用每次换工具都从头配一遍。

这篇文章适合三类人看。第一类是刚接触 Claude Code 或 Codex，连安装都还没跑通的新手，我会把 Node.js 环境、YAML 配置、工具安装这些基础环节讲透。第二类是已经在用单个工具，但想同时管理多套配置、接入不同模型的进阶用户，重点看配置编排和模型切换部分。第三类是遇到各种报错不知道怎么排查的，比如代理转发失败、模型不支持、组织权限被禁用这类问题，我在常见问题章节里整理了排查思路。

需要提前说明的是，openrig 本身不是一个官方大厂产品，它更像是社区里针对 AI 编程工具配置痛点衍生出来的实践方案。所以我会把重点放在"这类工具通常怎么设计、怎么用"上，结合 Claude Code 和 Codex 的实际配置经验来讲，而不是假设它有一个固定不变的官方文档。你读完应该能自己搭出一套可用的多工具配置环境。

2. 核心设计思路与方案选型拆解

2.1 为什么用 YAML 做配置层

AI 编程工具的配置项其实不少：模型端点、API 密钥、超时时间、代理设置、工具权限、上下文窗口大小等等。如果每个工具都用自己的一套 JSON 或 TOML 配置，你管理三个工具就要维护三套格式。YAML 的优势在于可读性强、支持注释、层级结构清晰，而且 Node.js 生态里解析 YAML 的库非常成熟，比如 js-yaml 这个包几乎是标配。

我实测下来，用 YAML 描述配置最大的好处是"改起来不心疼"。JSON 里少个逗号整个文件就废了，YAML 对缩进敏感但容错性好一些，而且能写注释。你可以在配置里标注"这行是给 Codex 用的""这个端点只在测试环境生效"，过两个月回来看还能看懂。openrig 这类项目选择 YAML 作为配置载体，本质上是在追求"人机都能读"的平衡点。

从技术实现角度看，Node.js 读取 YAML 配置的典型流程是这样的：

const fs = require('fs'); const yaml = require('js-yaml'); function loadConfig(path) { const raw = fs.readFileSync(path, 'utf8'); const config = yaml.load(raw); return config; }

这段代码看起来简单，但实际项目里要考虑的东西很多：配置文件不存在怎么办、YAML 语法错误怎么给出友好提示、环境变量怎么覆盖配置里的值、多环境配置怎么合并。openrig 如果要做成一个好用的工具，这些边界情况都得处理。

2.2 Node.js 作为运行时的必然性

Claude Code 和 Codex 这两套工具本身都是 Node.js 生态的产物。Claude Code 通过 npm 安装，Codex 的 CLI 也是 Node.js 写的。openrig 要跟它们打交道，用 Node.js 做运行时是最自然的选择——可以直接调用它们的 CLI、可以复用 npm 的包管理能力、可以用同一套环境变量体系。

Node.js 在这里扮演的角色不只是"跑个脚本"。它要负责：读取 YAML 配置、解析命令行参数、管理多个工具进程、处理模型端点的 HTTP 请求、做配置文件的读写和备份。这些任务用 Node.js 做都很顺手，尤其是异步 IO 和进程管理这块，Node.js 的 child_process 模块能让你方便地拉起 Claude Code 或 Codex 的子进程。

版本选择上有个坑要注意。热词里出现了 "error installing 24.21.0: node.js v24.21.0 is not yet released" 这种报错，说明有人试图安装一个还不存在的版本。Node.js 的版本号是有规律的，偶数版本是 LTS（长期支持），奇数版本是当前版。截至我写这篇文章的时候，稳妥的选择是 Node.js 20 LTS 或 22 LTS。不要盲目追最新版，AI 编程工具对 Node.js 版本往往有要求，太新或太旧都可能出问题。

2.3 多工具共存的配置编排逻辑

openrig 最核心的价值在于"编排"。什么叫编排？就是让 Claude Code 和 Codex 共享一部分配置，又各自保留独立设置。比如 API 密钥可以共用一套环境变量，但模型选择、工具权限、工作目录这些要分开。

我自己的做法是在项目根目录放一个openrig.yaml，结构大概是这样：

version: 1 tools: claude-code: enabled: true model: claude-sonnet-4-20250514 endpoint: https://api.anthropic.com env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} codex: enabled: true model: gpt-5.6-sol endpoint: https://api.openai.com/v1 env: OPENAI_API_KEY: ${OPENAI_API_KEY} shared: proxy: enabled: false timeout: 30000 logLevel: info

这种结构的思路是：顶层放共享配置，每个工具下面放自己的专属配置。${ANTHROPIC_API_KEY}这种写法表示从环境变量读取，避免把密钥硬编码在文件里。这是配置管理的基本安全实践，但很多人图省事直接写明文，一旦配置文件被提交到代码仓库就麻烦了。

2.4 模型接入的抽象层设计

热词里出现了 "codex接入deepseek"、"claude code 调用lmstudio的本地模型"、"使用cc switch 接入 deepseek v4, qwen, glm等模型" 这些内容，说明大家的核心诉求之一是"让工具支持更多模型"。Claude Code 默认只连 Anthropic 的模型，Codex 默认只连 OpenAI 的模型，但用户想用 DeepSeek、Qwen、GLM 或者本地跑的 LM Studio 模型。

openrig 这类工具要解决的就是这个"模型抽象"问题。它需要在配置里定义一个模型列表，每个模型有自己的端点、认证方式、请求格式，然后根据用户选择把请求转发到对应端点。这里的技术难点在于不同模型的 API 格式不完全一样，有的兼容 OpenAI 格式，有的有自己的格式，需要做适配转换。

提示：接入第三方模型时，先确认该模型是否提供 OpenAI 兼容接口。如果提供，配置会简单很多；如果不提供，就需要写适配层，工作量会大不少。

3. 环境搭建与核心配置实操

3.1 Node.js 环境准备与版本选择

装 Node.js 这件事看起来简单，但热词里 "node.js安装"、"node.js官网下载"、"安装node.js"、"node.js lts下载" 反复出现，说明确实有人卡在这一步。我推荐的做法是用版本管理工具，而不是直接下安装包。

Windows 用户可以用 nvm-windows，macOS 和 Linux 用户用 nvm。这样你可以随时切换 Node.js 版本，遇到某个工具要求特定版本时不用重装系统级的 Node.js。

# macOS/Linux 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装 Node.js 20 LTS nvm install 20 nvm use 20 # 验证 node -v npm -v

Windows 用户去 nvm-windows 的 GitHub 发布页下载安装包，装完之后在命令行里执行nvm install 20和nvm use 20。

这里有个细节：安装完 nvm 之后要重启终端，或者手动 source 一下配置文件，否则nvm命令找不到。我见过不少人装完 nvm 发现命令不识别，以为装失败了，其实就是没重载 shell 配置。

Node.js 装好之后，建议把 npm 的源配置一下。国内网络环境下，默认源有时候会很慢。可以用npm config set registry https://registry.npmmirror.com切换到国内镜像。这个操作不影响功能，只是加快包下载速度。

3.2 Claude Code 安装与基础配置

Claude Code 的安装方式是通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

装完之后执行claude命令应该能看到交互界面。第一次使用需要配置 API 密钥，可以通过环境变量设置：

export ANTHROPIC_API_KEY="你的密钥"

Windows 下用set ANTHROPIC_API_KEY=你的密钥或者通过系统环境变量界面设置。

热词里有个 "your organization has disabled claude subscription access for claude code" 的报错，这个问题的根源是账号权限。如果你用的是企业账号，管理员可能禁用了 Claude Code 的访问权限。这种情况自己折腾配置是解决不了的，需要联系账号管理员开通权限。个人账号一般不会遇到这个问题。

还有一个常见需求是 "vscode配置claude code" 和 "claude code for vs code"。Claude Code 有 VS Code 扩展，装完之后可以在编辑器里直接调用。配置方式和命令行版本基本一致，主要是 API 密钥和模型选择。VS Code 扩展的好处是能直接读取当前打开的项目上下文，不用手动指定工作目录。

3.3 Codex 安装与模型配置

Codex 的安装同样走 npm：

npm install -g @openai/codex

或者从官网下载安装包。热词里 "codex安装包"、"codex官网下载"、"codex安装 windows桌面版" 说明有人偏好桌面版。桌面版和 CLI 版功能上有差异，CLI 版更适合自动化和脚本集成，桌面版适合交互式使用。我建议两个都装，按场景切换。

Codex 的配置里有个容易出问题的地方是模型名称。热词里出现了{"detail":"the 'gpt-5.6-sol' model is not supported when using codex with a..."}这个报错，意思是 Codex 不支持你指定的模型。这种情况要么是模型名称写错了，要么是你的账号没有该模型的访问权限。解决方法是先确认账号可用的模型列表，然后在配置里填正确的名称。

Codex 接入第三方模型的配置通常涉及修改~/.codex/config.yaml或项目级的配置文件：

model: gpt-5.6-sol provider: name: openai base_url: https://api.openai.com/v1 api_key: ${OPENAI_API_KEY}

如果要接入 DeepSeek 这类兼容 OpenAI 格式的服务，把base_url改成对应的端点，api_key换成对应服务的密钥，model改成该服务支持的模型名即可。

3.4 YAML 配置文件编写要点

YAML 的语法坑不少，我整理几个最容易出错的点。

缩进必须用空格，不能用 Tab。这是 YAML 的铁律，混用 Tab 和空格会直接报解析错误。建议在编辑器里设置"Tab 转空格"，VS Code 默认对 YAML 文件就是这么处理的。

冒号后面要加空格。key:value是错的，key: value才是对的。这个细节很容易忽略，尤其是从 JSON 转过来的时候。

字符串里的特殊字符要引号包裹。比如model: gpt-5.6-sol没问题，但endpoint: https://api.example.com/v1?key=abc里的问号和等号可能引起歧义，最好写成endpoint: "https://api.example.com/v1?key=abc"。

多行字符串用|或>。|保留换行，>把换行转成空格。写提示词模板的时候会用到。

system_prompt: | 你是一个编程助手。 请用简洁的语言回答问题。 代码示例要标注语言类型。

热词里 "yolov10 yaml文件怎么创建" 和 "rstudio的yaml在哪里" 虽然跟 openrig 不是同一个领域，但说明 YAML 配置这件事在各行各业都有需求。核心语法是通用的，学会一套到哪都能用。

3.5 多工具切换与代理配置

"cc switch local proxy failed while handling codex endpoint /responses" 这个报错涉及代理转发。当你用 cc switch 这类工具在 Claude Code 和 Codex 之间切换，或者把请求转发到第三方端点时，代理层可能因为端点路径不匹配而失败。

排查这类问题的思路是：先确认代理工具监听的端口和路径，再确认目标端点的实际路径，看两者是否对得上。比如 Codex 的/responses端点，如果代理配置里写的是/v1/responses，就会 404。

我自己的代理配置习惯是加日志。在代理层把每个请求的入站路径和出站路径都打出来，对比一下就知道问题在哪。很多代理工具支持logLevel: debug这样的配置，打开之后能看到详细的转发记录。

注意：代理配置里如果涉及认证信息，确保不要把这些信息写进会提交到代码仓库的文件里。用环境变量或者本地不纳入版本控制的配置文件。

4. 完整实操流程与关键环节

4.1 从零搭建 openrig 配置环境

假设你现在什么都没装，我带你走一遍完整流程。

第一步，装 Node.js 20 LTS。按前面说的方法用 nvm 装，装完确认node -v输出 v20 开头的版本号。

第二步，装 Claude Code 和 Codex：

npm install -g @anthropic-ai/claude-code npm install -g @openai/codex

第三步，创建项目目录和配置文件：

mkdir my-ai-project && cd my-ai-project touch openrig.yaml

第四步，编辑openrig.yaml，填入你的配置。参考前面的结构，把 API 密钥用环境变量引用。

第五步，设置环境变量。在~/.bashrc或~/.zshrc里加上：

export ANTHROPIC_API_KEY="sk-ant-xxx" export OPENAI_API_KEY="sk-xxx"

然后source ~/.bashrc让配置生效。

第六步，验证。执行claude --version和codex --version确认两个工具都能正常运行。然后在一个测试项目里分别用两个工具做一次简单操作，确认模型调用正常。

这套流程走下来大概十五到二十分钟，主要时间花在下载 npm 包上。如果网络慢，可以先把 npm 源切到国内镜像。

4.2 接入本地模型的配置方法

"claude code 调用lmstudio的本地模型" 这个需求很典型。LM Studio 可以在本地跑开源模型，并提供 OpenAI 兼容的 API 端点，默认地址是http://localhost:1234/v1。

配置 Claude Code 接入 LM Studio 的思路是：把 Claude Code 的端点指向 LM Studio，模型名填 LM Studio 里加载的模型名称。但 Claude Code 的请求格式和 OpenAI 格式不完全一样，所以通常需要一个转换层。有些社区工具就是做这个转换的。

Codex 接入 LM Studio 相对简单，因为 Codex 本身就支持 OpenAI 格式：

model: local-model provider: name: openai base_url: http://localhost:1234/v1 api_key: not-needed

LM Studio 不需要 API 密钥，随便填一个占位符就行。模型名要跟 LM Studio 里加载的模型对应，可以在 LM Studio 的界面上看到。

本地模型的好处是数据不出本机、没有调用费用、不受网络影响。缺点是模型能力通常不如云端大模型，复杂任务可能搞不定。我的建议是简单任务用本地模型，复杂任务切云端。

4.3 多环境配置管理

实际项目里往往有多个环境：开发、测试、生产。每个环境的模型端点、密钥、超时设置可能都不一样。openrig 这类工具通常支持多环境配置。

一种常见的做法是用不同的配置文件：

config/ openrig.dev.yaml openrig.test.yaml openrig.prod.yaml

然后通过环境变量或命令行参数指定用哪个：

OPENRIG_ENV=dev openrig run

另一种做法是在单个配置文件里用 profile 区分：

profiles: dev: model: local-model endpoint: http://localhost:1234/v1 prod: model: claude-sonnet-4-20250514 endpoint: https://api.anthropic.com default_profile: dev

我偏好第二种，因为所有配置在一个文件里，对比和修改都方便。但要注意这个文件不能提交到公开仓库，或者至少要把密钥部分抽到环境变量里。

4.4 配置验证与健康检查

配置写完不代表能用，得验证。我习惯写一个简单的检查脚本：

const fs = require('fs'); const yaml = require('js-yaml'); function validateConfig(path) { try { const config = yaml.load(fs.readFileSync(path, 'utf8')); const errors = []; if (!config.tools) { errors.push('缺少 tools 配置段'); } for (const [name, tool] of Object.entries(config.tools || {})) { if (tool.enabled && !tool.model) { errors.push(`${name} 已启用但未指定模型`); } if (tool.env) { for (const [key, value] of Object.entries(tool.env)) { if (typeof value === 'string' && value.startsWith('${') && !process.env[key]) { errors.push(`${name} 引用的环境变量 ${key} 未设置`); } } } } return errors; } catch (e) { return [`YAML 解析失败: ${e.message}`]; } }

这个脚本能提前发现大部分配置问题：YAML 语法错误、必填项缺失、环境变量未设置。在启动工具之前跑一遍，比等到运行时才报错要高效得多。

4.5 工具权限与安全设置

AI 编程工具能执行终端命令，这是能力也是风险。Claude Code 有 "如何直接执行终端命令" 这个热词，说明大家很关心这个功能。默认情况下，工具执行命令前会请求确认，但你可以配置成自动执行。

我的建议是：在受控的开发环境里可以开自动执行，提高效率；在生产环境或者涉及敏感数据的项目里，保持手动确认。配置项通常叫autoApprove或dangerouslySkipPermissions之类的名字，看到这类选项要谨慎。

tools: claude-code: permissions: autoApprove: false allowedCommands: - "npm test" - "git status" - "ls"

白名单机制比全开或全关都安全。只允许工具执行你明确认可的命令，其他的一律需要确认。

5. 常见问题排查与避坑经验

5.1 安装类问题速查

安装类问题九成出在环境变量和权限上。我踩过最坑的一次是在公司电脑上，npm 全局目录被 IT 策略限制，装什么都失败。后来改用 nvm 管理 Node.js，全局包装在用户目录下，问题就没了。

5.2 模型接入类问题排查

"codex无法加载组织设置" 这个报错通常跟账号配置有关。Codex 会读取组织级别的设置，如果组织配置有问题或者账号没有正确关联组织，就会报这个错。解决方法是检查账号状态，确认组织设置是否完整。

"the 'gpt-5.6-sol' model is not supported" 这类模型不支持的问题，排查顺序是：先确认模型名称拼写正确，再确认账号有该模型权限，最后确认工具版本支持该模型。有时候工具版本太旧，新模型还没加进去，升级工具就能解决。

接入第三方模型时最常见的错误是端点路径不对。OpenAI 格式的端点是/v1/chat/completions，但有些服务用的是/v1/responses或其他路径。配置之前先看目标服务的文档，确认正确的端点路径。

5.3 代理转发失败排查

"cc switch local proxy failed while handling codex endpoint /responses" 这个报错我在调试时遇到过类似的。代理转发失败通常有三个原因：端口被占用、路径不匹配、认证信息缺失。

排查步骤：

1. 确认代理进程在运行，端口在监听。用netstat -an | grep 端口号或lsof -i :端口号检查。
2. 确认代理配置里的目标端点路径和实际服务路径一致。
3. 确认认证头正确传递。有些代理会丢掉 Authorization 头，导致目标服务返回 401。
4. 看代理日志。把日志级别调到 debug，能看到完整的请求和响应。

我自己的经验是，代理问题八成出在路径上。尤其是 Codex 的/responses端点，跟传统的/chat/completions不一样，配置的时候容易搞混。

5.4 配置文件类问题

YAML 解析失败是最常见的配置问题。报错信息通常会指出行号，照着行号去看那一行的缩进和冒号。我总结了一个检查清单：

• 缩进是否全用空格，有没有混入 Tab
• 冒号后面是否有空格
• 字符串里的特殊字符是否加了引号
• 列表项的-后面是否有空格
• 多行字符串的|或>是否正确使用

还有一个隐蔽的问题是编码。YAML 文件要用 UTF-8 编码，如果编辑器保存成了 GBK 或其他编码，中文注释会导致解析失败。VS Code 右下角可以看到当前文件编码，确认是 UTF-8。

5.5 账号权限类问题

"your organization has disabled claude subscription access for claude code" 这个报错前面提过，是组织管理员禁用了访问。个人账号一般不会遇到，企业账号需要联系管理员。

还有一种情况是订阅类型不支持。某些订阅计划可能不包含 Claude Code 的使用权限，需要升级订阅。这个在账号的订阅管理页面能看到。

Codex 的 "codex登录" 问题也类似，登录失败可能是账号问题、网络问题或工具版本问题。先确认账号能正常登录官网，再排查工具侧的配置。

5.6 性能与稳定性优化

多工具同时运行时，资源占用会比较高。我的做法是不同时开多个工具，用哪个开哪个。如果确实需要并行，注意内存和 CPU 占用，必要时升级硬件配置。

网络稳定性对云端模型调用影响很大。如果经常超时，可以适当调大超时时间：

shared: timeout: 60000 retry: maxAttempts: 3 backoff: 1000

重试机制能解决偶发的网络抖动，但不要设太多重试次数，否则一个请求卡很久。三次重试、每次间隔递增，是比较合理的配置。

日志级别在排查问题时调成 debug，平时调成 info 或 warn，避免日志文件膨胀。日志文件要定期清理，或者配置轮转。

6. 进阶玩法与扩展思路

6.1 用脚本自动化配置切换

如果你经常在多个项目之间切换，每个项目用不同的模型和配置，可以写个脚本自动切换。核心思路是根据当前目录判断用哪个配置，然后设置对应的环境变量。

#!/bin/bash # switch-rig.sh PROJECT_DIR=$(pwd) CONFIG_FILE="$PROJECT_DIR/openrig.yaml" if [ ! -f "$CONFIG_FILE" ]; then echo "当前目录没有 openrig.yaml，使用默认配置" exit 0 fi # 读取配置里的默认 profile PROFILE=$(yq '.default_profile' "$CONFIG_FILE") echo "切换到 profile: $PROFILE" # 根据 profile 设置环境变量 export OPENRIG_PROFILE="$PROFILE"

这个脚本用到了yq这个命令行 YAML 处理工具，需要单独安装。它的作用是在 shell 里方便地读取 YAML 字段，比用 grep 和 sed 靠谱得多。

6.2 配置模板化与复用

多个项目共用一套基础配置时，可以用 YAML 的锚点和引用来复用：

defaults: &defaults timeout: 30000 logLevel: info retry: maxAttempts: 3 tools: claude-code: <<: *defaults model: claude-sonnet-4-20250514 codex: <<: *defaults model: gpt-5.6-sol

&defaults定义锚点，<<: *defaults引用锚点内容。这样改一处默认配置，所有引用它的地方都跟着变。YAML 的这个特性在配置项多的时候特别有用，能避免重复和遗漏。

6.3 与版本控制配合的最佳实践

配置文件纳入版本控制是好事，但密钥不能进去。我的做法是：

• openrig.yaml提交到仓库，里面用${ENV_VAR}引用密钥
• .env.example提交，列出需要设置哪些环境变量，但不含真实值
• .env不提交，加入.gitignore，里面放真实密钥

这样新同事克隆仓库后，照着.env.example设置自己的.env就能跑起来，密钥也不会泄露。

6.4 监控与日志分析

长期使用的话，建议记录每次模型调用的耗时和结果，方便分析哪个模型在什么任务上表现好。可以在代理层加日志，记录请求的模型、耗时、token 用量。

function logRequest(model, startTime, endTime, tokens) { const entry = { timestamp: new Date().toISOString(), model, duration: endTime - startTime, tokens }; fs.appendFileSync('usage.log', JSON.stringify(entry) + '\n'); }

积累一段时间后，你就能看出哪个模型性价比高、哪个时段响应慢、哪些任务消耗 token 多。这些数据对优化配置很有价值。

6.5 社区工具与生态整合

围绕 Claude Code 和 Codex 已经有不少社区工具，比如做模型切换的、做代理转发的、做配置管理的。openrig 这类项目如果能跟这些工具配合使用，能力会更强。

选择社区工具时注意几点：看更新频率，长期不更新的可能不兼容新版本；看 issue 处理情况，活跃维护的项目更可靠；看文档完整度，文档差的工具用起来费劲。不要盲目追新，稳定可用比功能多更重要。

我在实际使用中的体会是，配置管理这件事没有一劳永逸的方案。工具在更新、模型在迭代、需求在变化，配置也要跟着调整。与其追求一个完美的配置，不如建立一套快速调整配置的方法——知道改哪个文件、改完怎么验证、出问题怎么回滚。这套方法比任何具体配置都值钱。

最后分享一个小技巧：把常用的配置片段存成代码片段，在编辑器里设置快捷键。比如输入rigbase就展开成基础配置模板，输入rigmodel就展开成模型配置段。这样写新配置的时候能省不少时间，也能减少手误。