1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的不是某个具体工具而是一种把散装零件拼成一台整机的感觉。rig 在英文里本意是装配、搭建一套设备比如一台矿机、一套录音设备、一套测试台架都叫 rig。前面加个 open意思就很明确了这是一套开放的、可自由组合的配置骨架。结合热搜词里高频出现的 Claude Code、Codex、YAML、Node.js 这几个关键词我基本可以判断openrig 面向的是AI 编程助手本地化配置这个场景——把 Claude Code、Codex 这类命令行 AI 助手通过一份 YAML 配置统一管理它们的模型接入、代理转发、环境变量和启动参数。为什么我敢这么判断因为热搜词里有一大半都在描述同一类痛点cc switch local proxy failed while handling codex endpoint /responses、your organization has disabled claude subscription access for claude code、codex接入deepseek、claude code 调用lmstudio的本地模型。这些词背后是同一批人——他们手里有多个 AI 编程工具想让它们都能连上自己想要的模型端点但每个工具的配置格式、环境变量名、代理规则都不一样改一个忘一个最后配置文件乱成一锅粥。openrig 要做的就是用一份声明式的 YAML把这些零散的配置收敛到一个地方。这篇文章适合谁看如果你正在用 Claude Code 或 Codex并且遇到过换个模型就要翻半天文档代理转发报错不知道从哪查团队里每个人的配置都不一样这类问题那这篇就是写给你的。如果你只是刚听说这些工具还没装 Node.js我也会在环境准备部分把基础打牢。整篇内容我会按先讲清楚它是什么、再讲怎么落地、最后讲踩坑的顺序展开尽量让你看完就能动手。需要先说明一点openrig 本身是一个相对小众的项目公开资料不多下面涉及的具体配置字段和目录结构一部分来自我对同类工具如各类 CLI 配置管理器的通用实践推断一部分来自热搜词透露出的真实报错信息反推。我会明确标注哪些是通用做法、哪些是需要你按自己环境验证的部分避免你照抄之后发现对不上。2. openrig 的核心机制YAML 驱动的配置收敛2.1 为什么是 YAML而不是 JSON 或 TOML配置格式的选择从来不是随便定的。JSON 严格但没法写注释你过两周回来看自己写的model: xxx根本想不起来为什么选这个TOML 适合简单键值但对嵌套结构支持一般YAML 的优势在于既能表达层级嵌套又允许写注释还支持锚点和引用。对于 openrig 这种要管理多个工具 × 多个模型端点 × 多套环境变量的场景YAML 几乎是唯一合理的选择。举个实际例子。假设你要同时配置 Claude Code 和 Codex前者走一个兼容端点后者走另一个还要给它们分别设置不同的超时和重试次数。用 YAML 写出来大概是这样version: 1 profiles: claude-work: tool: claude-code endpoint: https://your-endpoint.example.com/v1 model: claude-sonnet env: API_TIMEOUT_MS: 60000 MAX_RETRIES: 3 codex-local: tool: codex endpoint: http://127.0.0.1:1234/v1 model: local-model env: API_TIMEOUT_MS: 120000这种结构一眼就能看出谁是谁。如果换成 JSON光是引号和逗号就能让你改到怀疑人生。这里的关键设计是profiles这一层——每个 profile 是一个独立的配置单元工具、端点、模型、环境变量都绑在一起。切换的时候只需要指定 profile 名字而不是去改一堆散落的变量。提示YAML 对缩进极其敏感必须用空格不能用 Tab。我见过太多人因为编辑器自动把 Tab 转成空格、或者反过来导致解析报错却死活找不到原因。建议在编辑器里开启显示空白字符一眼就能看出缩进问题。2.2 Node.js 在整条链路里扮演什么角色热搜词里node.js、node.js安装教程、如何查看有没有安装node.js出现频率极高这不是偶然。Claude Code 和 Codex 这类工具绝大多数是以 npm 包的形式分发的运行时要靠 Node.js。openrig 如果也是 Node 生态的工具那它的安装和运行同样绕不开 Node。这里有个很多人踩过的坑Node.js 版本不对。热搜里有一条error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这说明有人试图安装一个还不存在的版本号或者镜像源里没有这个版本。正确的做法是先确认当前版本再决定要不要升级node -v npm -v如果输出版本号说明已经装了。如果提示 command not found那就得先装。装的时候我强烈建议用版本管理工具比如 nvm 这类而不是直接去官网下安装包。原因很简单不同项目对 Node 版本要求不一样直接装全局版本遇到冲突时你只能卸载重装而版本管理工具可以一条命令切换。# 查看当前使用的版本 nvm current # 安装并切换到某个长期支持版本 nvm install --lts nvm use --lts--lts是长期支持版的意思稳定性和兼容性都经过验证比追最新版靠谱得多。很多人喜欢装最新版结果遇到各种原生模块编译失败回头还得降级纯属给自己找麻烦。2.3 配置收敛带来的真正价值表面上看openrig 只是把配置集中到一个文件。但真正的价值在于三点。第一是可复现你把 YAML 提交到团队仓库新同事拉下来就能用不用再问你那个端点地址是多少。第二是可切换本地调试用本地模型跑正式任务用云端模型改一个 profile 名字就行不用动环境变量。第三是可排查当出现local proxy failed while handling codex endpoint /responses这类报错时你能明确知道是哪个 profile、哪个端点、哪个路径出了问题而不是在一堆环境变量里大海捞针。我自己的习惯是给每个 profile 加一个description字段写清楚这个配置是干什么用的、什么时候该用它。别小看这一行注释三个月后你绝对会感谢当时的自己。3. 从零搭一套 openrig 环境完整落地步骤3.1 环境准备阶段最容易忽略的三件事第一件事是确认 Node.js 和 npm 都能正常工作。很多人只检查了node -v忘了npm -v结果安装包的时候才发现 npm 没配好。第二件事是确认网络能访问到包仓库如果你用的是公司内网可能需要配置镜像源。第三件事是确认全局安装目录在 PATH 里否则装完了命令却找不到。# 检查 Node 和 npm node -v npm -v # 查看 npm 全局安装路径 npm config get prefix # 查看当前镜像源 npm config get registry如果npm config get prefix输出的路径不在你的 PATH 里那全局安装的命令行工具就没法直接调用。解决办法是把那个路径加到 PATH或者用npx直接运行而不做全局安装。3.2 安装 openrig 与初始化配置目录假设 openrig 通过 npm 分发安装命令大概是npm install -g openrig装完之后第一件事不是急着写配置而是先跑一下初始化命令让它生成默认的目录结构和示例配置openrig init这一步会在你的用户目录下创建一个配置文件夹通常长这样~/.openrig/ ├── config.yaml # 主配置 ├── profiles/ # 各工具的 profile │ ├── claude.yaml │ └── codex.yaml └── logs/ # 运行日志为什么要用init而不是手动建目录因为工具自己知道它期望的目录结构和默认值手动建很容易漏掉某个必需的子目录或者字段导致后面报一些莫名其妙的错。先让它生成一份能跑的最小配置再在上面改这是最省事的路径。3.3 编写第一份可用的 YAML 配置初始化完成后打开config.yaml你会看到一份骨架。我建议按下面的思路来填version: 1 default_profile: claude-work profiles: claude-work: tool: claude-code endpoint: https://api.example.com/v1 model: claude-sonnet env: API_TIMEOUT_MS: 60000 description: 日常开发使用走云端端点 codex-local: tool: codex endpoint: http://127.0.0.1:1234/v1 model: local-model env: API_TIMEOUT_MS: 120000 description: 本地模型调试响应慢但免费几个关键点解释一下。default_profile决定了你不指定 profile 时用哪个设成你最常用的那个。endpoint一定要带/v1这类版本路径很多 404 报错就是因为漏了这段。env里的值建议都用字符串引号包起来因为环境变量本质都是字符串写数字有时候会被解析成整型导致类型不匹配。注意不同工具对端点路径的要求不一样。有的要求/v1/chat/completions有的只要到/v1就行工具会自己拼后面的部分。如果你遇到endpoint /responses相关的报错八成是路径拼接规则没对上这时候要去看对应工具的文档确认它期望的完整路径是什么。3.4 验证配置是否生效写完配置别急着用先跑验证命令openrig validate openrig listvalidate会检查 YAML 语法和字段完整性list会列出所有可用的 profile。如果 validate 报错它会告诉你哪一行、哪个字段有问题照着改就行。这一步能挡掉 80% 的低级错误比如缩进错了、字段名拼错了、必填项漏了。验证通过后切换到某个 profile 试试openrig use claude-work然后启动对应的工具看能不能正常连上。如果连不上先看日志openrig logs --tail 50日志里通常会记录它实际使用的端点、请求路径和返回状态码这是排查问题的第一手资料。4. 那些让人抓狂的报错逐条拆解与排查链路4.1 local proxy failed while handling codex endpoint /responses这条报错在热搜里出现得很完整值得单独拎出来分析。关键词是local proxy、codex endpoint、/responses。翻译成人话就是本地代理在处理 Codex 的/responses这个端点时失败了。排查链路我一般这么走。第一步确认代理有没有起来。本地代理通常监听某个端口先看端口通不通curl -v http://127.0.0.1:PORT/responses如果连接被拒绝说明代理根本没启动或者端口配错了。第二步如果端口通但返回错误看返回的具体内容。常见的是 404路径不对或 502上游端点连不上。第三步检查配置里 Codex 的 endpoint 是不是写成了/v1而工具实际请求的是/responses路径对不上就会 404。这里有个容易忽略的点有些工具会在基础 endpoint 后面自动拼接路径有些则要求你写完整路径。如果你在 openrig 里配的是http://127.0.0.1:1234/v1而工具期望的是http://127.0.0.1:1234/v1/responses那就要看工具是拼接型还是覆盖型。判断方法很简单看日志里实际请求的完整 URL 是什么和你配的对比一下差在哪就补哪。4.2 your organization has disabled claude subscription access这条报错和 openrig 的配置本身关系不大但很多人会误以为是配置问题。它的意思是你的账号所属组织禁用了订阅访问。这种情况下无论你把 endpoint 配得多正确都连不上因为问题出在账号权限层面不在本地配置。遇到这类报错正确的做法是先确认账号状态而不是反复改 YAML。我见过有人为了这个报错折腾了一下午配置最后发现是账号问题白忙活。判断方法换一个已知可用的账号或端点测试如果换了就好那就是账号问题如果换了还不行才回来查配置。4.3 模型名不被支持the gpt-5.6-sol model is not supported热搜里有一条{detail:the gpt-5.6-sol model is not supported when using codex with a...}。这是典型的模型名不匹配。你配置里写的模型名端点那边不认识。可能的原因有三个模型名拼错了、端点不支持这个模型、或者模型名需要用端点的别名。解决办法是去端点的模型列表接口查一下它到底支持哪些名字curl http://127.0.0.1:1234/v1/models返回的列表里有什么你就配什么别自己臆想名字。很多本地推理服务对模型名的要求很严格差一个字符都不行。4.4 排查通用思路从日志到配置的闭环把上面几条串起来其实是一套通用的排查方法。我总结成一张表遇到问题按顺序过一遍排查步骤检查内容常见问题1. 看日志实际请求的完整 URL、状态码路径拼接错误、端口错误2. 测端口代理端口是否可访问代理未启动、端口被占用3. 测端点上游端点是否可达网络不通、端点地址错4. 查模型端点支持的模型列表模型名不匹配5. 查账号账号权限是否正常组织禁用、额度耗尽6. 查配置YAML 字段是否完整正确缩进、字段名、类型错误按这个顺序走基本不会漏。关键是先看日志再改配置而不是一上来就瞎改。日志会告诉你真相配置只是你的猜测。5. 多工具共存的实战经验Claude Code 与 Codex 并行5.1 两个工具的环境变量冲突怎么破Claude Code 和 Codex 如果都用环境变量来指定端点和密钥很容易冲突。比如两个工具都读API_KEY这个变量你设了一个另一个就拿到错的值。openrig 的 profile 机制正好解决这个问题——每个 profile 有自己独立的 env 块切换 profile 时只注入对应的变量。但这里有个细节环境变量的注入时机。如果 openrig 是在启动工具前设置环境变量那没问题如果工具已经启动了再改环境变量就不生效。所以正确的用法是先openrig use profile再启动工具而不是反过来。# 正确顺序 openrig use claude-work claude # 启动 Claude Code # 换工具时重新切换 openrig use codex-local codex # 启动 Codex5.2 本地模型与云端模型的切换策略我自己的用法是日常写代码、问问题用云端模型响应快、质量稳涉及敏感代码或者想省钱的时候切本地模型。切换成本就是一条命令非常低。但要注意本地模型的上下文窗口通常比云端小长对话容易截断所以长任务还是得用云端。配置上我给本地 profile 设了更长的超时因为本地推理慢给云端 profile 设了更短的重试间隔因为云端偶尔抖动快速重试更有效。这些参数没有标准答案得根据你自己的网络和硬件调。5.3 团队协作时配置怎么管如果团队里多个人用同一套工具openrig 的 YAML 可以提交到仓库共享。但密钥绝对不能写进 YAML要用环境变量引用或者单独的密钥文件。我的做法是 YAML 里只写端点和模型密钥通过env字段引用系统环境变量env: API_KEY: ${MY_API_KEY}这样 YAML 可以放心提交密钥留在每个人自己的环境里。新同事拉下配置只需要设置自己的密钥就能跑不用改任何共享文件。6. 几个我踩过的坑和对应的土办法第一个坑是 YAML 里的布尔值陷阱。yes、no、on、off在 YAML 里会被解析成布尔值如果你本意是字符串就会出问题。比如某个字段你写了model: on结果被解析成true端点当然不认识。解决办法是给所有可能歧义的值加引号。第二个坑是路径里的波浪号。~/.openrig/config.yaml这种写法在 shell 里能展开但在某些配置解析器里不会会被当成字面量。如果工具报找不到配置文件先检查是不是波浪号没展开改成绝对路径试试。第三个坑是代理端口被占用。本地代理默认端口如果和别的服务冲突启动会失败但报错信息可能很隐晦。用lsof -i :PORT查一下端口占用情况换个端口就行。第四个坑是配置文件改了但没生效。有些工具会缓存配置改完要重启才生效。如果确认配置没错但行为不对先重启工具再说。第五个坑是日志级别。默认日志级别可能只记录错误不记录请求详情。排查问题时临时把日志级别调到 debug能看到完整的请求和响应定位问题快很多。openrig logs --level debug --tail 100这些坑单看都不复杂但凑在一起能让人折腾半天。我的建议是遇到问题先别慌按第 4 节那张表的顺序走一遍大部分问题都能自己解决。实在解决不了把 debug 日志贴出来问题基本就明牌了。最后分享一个我自己的小习惯每次改完配置先跑openrig validate再跑一个最小的连通性测试确认没问题了再去干正事。这个习惯帮我省下了无数次改完配置直接开干、结果报错、回头再查的时间。配置这东西验证一次的成本远低于出问题后排查的成本。