1. openrig 到底想解决什么问题第一次看到openrig这个词是在几个折腾 Claude Code 和 Codex 的群里。有人丢出一句openrig 跑通了底下立刻有人追问配置怎么写的。我当时的反应是又一个新工具点进去看了半天发现它并不是某个具体的软件包而更像是一类做法的统称——把 Claude Code、Codex 这类命令行 AI 编程助手通过一份结构化的 YAML 配置接到本地或第三方的模型服务上让它们不再死绑官方订阅。这个需求是怎么冒出来的用过 Claude Code 的人都知道它默认走官方账号体系一旦组织层面把订阅权限关了终端里就会甩出一句your organization has disabled claude subscription access for claude code直接卡死。Codex 那边也类似登录、组织设置、模型支持列表任何一环对不上就报错比如the gpt-5.6-sol model is not supported when using codex with a...。于是大家开始想办法能不能让这些工具走自己的模型端点能不能用 DeepSeek、Qwen、GLM 这些模型来驱动同样的交互体验openrig就是在这个背景下被反复提起的。它本质上是一套配置驱动的接入思路用 YAML 描述模型端点、鉴权方式、请求路径、模型映射然后让 Claude Code 或 Codex 把请求打到这个配置指定的地方。关键词里出现的cc switch local proxy failed while handling codex endpoint /responses就是这条链路上最典型的报错——代理层在处理 Codex 的/responses端点时挂了说明配置里的路径或协议对不上。所以这篇内容适合谁看三类人一是被官方订阅权限卡住、想换自己模型端点的开发者二是想用本地模型比如通过 LM Studio 起服务驱动 Claude Code 的折腾党三是单纯想搞明白 YAML 配置、Node.js 环境、Codex/Claude Code 安装这一整套流程到底怎么串起来的新手。我会把从环境准备到配置落地、再到排错的完整链路讲清楚重点放在为什么这么配和配错了会怎样。需要先说明一点openrig目前没有一个官方统一的仓库或文档它更多是社区里对这类配置方案的口头称呼。所以下面讲的内容是基于这类工具常见的实现方式和我自己实测过的路径来展开的具体字段名可能因你用的版本不同而略有差异但底层逻辑是通的。2. 环境底座Node.js 与包管理器的选择逻辑2.1 为什么这类工具几乎都绕不开 Node.jsClaude Code 和 Codex 的 CLI 版本绝大多数是通过 npm 分发的。这意味着你机器上得有一个能跑的 Node.js 环境。很多人卡在第一步不是因为不会装而是装错了版本。热搜词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava就是典型——有人手动指定了一个还没正式发布的版本号npm 自然找不到。我的建议很直接装 LTS 版本别追最新。Node.js 官网下载页上会明确标出 LTS长期支持和 Current当前最新两条线。AI 编程助手这类工具对 Node 版本的要求通常是不低于某个下限而不是必须最新。用 LTS 能避开大量因为 V8 引擎或 API 变动导致的兼容问题。具体操作上Windows 用户直接去 Node.js 官网下载 LTS 的.msi安装包一路下一步即可。macOS 用户如果装了 Homebrewbrew install node20这类命令更省事。Linux比如 Ubuntu用户我更推荐用 nvm 来管理版本因为后面你可能需要为不同项目切换 Node 版本。# Ubuntu 下用 nvm 安装 Node.js LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v npm -v装完之后node -v和npm -v都要能正常输出。如果node有输出但npm报 command not found多半是 PATH 没配好检查一下 nvm 的初始化脚本有没有写进.bashrc或.zshrc。2.2 全局安装还是本地安装这里有个坑Claude Code 和 Codex 的安装命令通常是npm install -g全局装。全局装的好处是任何目录下都能直接敲命令坏处是版本冲突时不好排查。我踩过一次坑全局装了两个版本的 CLI结果which claude指向的那个和实际执行的不是同一个报错信息看得我一头雾水。排查方法很简单# 查看全局安装的包 npm list -g --depth0 # 查看命令实际指向的路径 which claude which codex如果发现路径指向了 nvm 的某个旧版本目录而你现在用的是新版本 Node那就是版本错位了。解决办法是先npm uninstall -g卸掉再用当前 Node 版本重新装。提示如果你同时用 nvm 管理多个 Node 版本全局包是跟着 Node 版本走的。切换 Node 版本后之前装的全局 CLI 可能就消失了需要在新版本下重装。这是很多人明明装过却找不到命令的根本原因。2.3 YAML 解析依赖别忽略这个隐形前提openrig这类方案的核心是 YAML 配置而解析 YAML 需要对应的库。如果你是用 Node.js 生态的工具通常它内部已经带了 YAML 解析器比如js-yaml你不需要单独装。但如果你自己写脚本去读配置就得注意了。热搜里yaml安装、yaml文件、yolov10 yaml文件怎么创建、rstudio的yaml在哪里这些词混在一起其实反映了一个普遍困惑YAML 不是一个需要安装的软件它是一种文件格式。你需要的不是装 YAML而是装能读写 YAML 的库或者用一个支持 YAML 语法高亮的编辑器。# 如果要在 Node.js 项目里自己解析 YAML npm install js-yaml # Python 环境下 pip install pyyaml编辑器方面VS Code 原生就支持 YAML 语法高亮装个 YAML 扩展还能做 schema 校验配置写错了会直接标红。这个对排查openrig配置问题帮助很大强烈建议装上。3. openrig 配置文件的字段拆解3.1 一份典型配置长什么样既然openrig没有官方标准我就拿社区里流传最广的一种结构来讲。它的核心思路是定义多个provider模型提供方每个 provider 包含端点地址、鉴权信息、模型映射然后指定当前激活哪个 provider。# openrig 配置示例结构示意 providers: - name: local-lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - name: local-model map_to: gpt-4o-mini - name: deepseek type: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} models: - name: deepseek-chat map_to: gpt-4o active: local-lmstudio这份配置里几个关键字段值得逐个说。type决定了请求用什么协议发出去。openai-compatible是最常见的因为大量第三方模型服务都兼容 OpenAI 的/v1/chat/completions接口格式。Claude Code 和 Codex 原本走的是各自官方的协议openrig这一层做的就是协议转换——把工具发出的请求翻译成目标端点能听懂的格式。base_url是端点根地址。这里最容易出错的地方是结尾的/v1要不要带。有的服务要求带有的要求不带带错了就是 404。我的经验是先看服务商文档给的示例文档里curl命令打到哪个地址你就填哪个。api_key支持环境变量引用${VAR_NAME}是个好设计。把密钥写死在配置文件里一旦这个文件被同步到 Git 仓库密钥就泄露了。用环境变量配置文件可以放心提交。3.2 模型映射为什么需要 map_tomap_to这个字段是很多人第一次看会懵的地方。为什么不能直接用目标模型的真实名字原因在于 Claude Code 和 Codex 内部会硬编码一些模型名。比如 Codex 可能默认请求gpt-5.6-sol这样的名字而你的第三方端点根本不认识这个名字于是报the gpt-5.6-sol model is not supported。map_to的作用就是做一层名字替换工具请求gpt-5.6-sol配置层把它改写成你端点真正支持的deepseek-chat或qwen-max。models: - name: gpt-5.6-sol # 工具内部请求的名字 map_to: deepseek-chat # 实际发给端点的名字这个映射关系需要你两边都清楚一边是工具会请求哪些模型名看它的文档或抓包另一边是你的端点支持哪些模型名看服务商文档。两边对上了请求才能通。注意有些工具会在启动时先发一个模型列表请求来探测可用模型。如果你的端点不支持/v1/models这个接口工具可能直接判定无可用模型而拒绝启动。这种情况下配置层需要额外做一个假的模型列表响应。这是openrig类方案里比较进阶的处理遇到再说。3.3 端点路径/responses 与 /chat/completions 的分歧热搜里那条cc switch local proxy failed while handling codex endpoint /responses点出了一个关键差异Codex 用的端点路径和传统 OpenAI 兼容接口不一样。传统 OpenAI 兼容服务走的是/v1/chat/completions。而 Codex 在某些版本里走的是/responses这个路径这是它自己的一套请求格式。如果你的代理层只会转发/chat/completions遇到/responses就不知道怎么办于是报 failed while handling codex endpoint /responses。解决思路有两条一是让代理层同时支持这两个路径把/responses的请求转换成/chat/completions再发出去二是找一个本身就支持/responses格式的端点。前者更通用但需要代理层做协议转换工作量大一些。# 路径重写示意 routes: - from: /responses to: /v1/chat/completions transform: codex-to-openai这段配置的意思是收到/responses的请求转成/v1/chat/completions并做一次 codex 到 openai 格式的转换。具体转换逻辑取决于你的代理实现这里只是说明思路。4. 从零跑通一条链路的完整步骤4.1 先确认模型端点本身是通的很多人一上来就配 Claude Code结果报错分不清是端点的问题还是工具的问题。正确的顺序是先用 curl 确认端点能通再配工具。以本地 LM Studio 为例启动服务后它默认监听http://127.0.0.1:1234。先测一下curl http://127.0.0.1:1234/v1/models如果返回一个模型列表的 JSON说明端点活着。再测对话接口curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d { model: local-model, messages: [{role: user, content: 你好}] }能返回正常回复端点这一层就没问题了。这一步看着简单但能帮你排除掉一大半到底是哪坏了的困惑。4.2 安装并验证 Claude Code / CodexClaude Code 的安装官方推荐方式是 npm 全局装npm install -g anthropic-ai/claude-code装完敲claude看能不能起来。如果提示命令找不到回到 2.2 节检查全局包路径。Codex 类似具体包名以官方文档为准。VS Code 用户还可以装对应的扩展在编辑器里直接用。热搜里vscode配置claude code、claude code for vs code、vscode接入claude code说的都是这个。扩展装好后通常需要在设置里指定 CLI 的路径或者让它自动探测。Ubuntu 用户注意如果 CLI 装好后运行报权限错误检查一下安装目录的执行权限。有时候 npm 全局目录的权限设置不对会导致命令无法执行。4.3 把配置接上去这一步是openrig的核心。你需要找到 Claude Code 或 Codex 读取配置的位置。常见的有几种环境变量比如ANTHROPIC_BASE_URL、OPENAI_BASE_URL这类直接指定端点地址。配置文件工具自己的配置文件通常在用户主目录下的隐藏文件夹里。代理层起一个本地代理工具指向代理代理再按openrig配置转发。第三种最灵活也是openrig这个名字最贴切的用法。代理层读 YAML 配置决定把请求发到哪、怎么转换。热搜里cc switch就是这类代理/切换工具的一种。# 通过环境变量指定端点以 OpenAI 兼容为例 export OPENAI_BASE_URLhttp://127.0.0.1:1234/v1 export OPENAI_API_KEYnot-needed设完环境变量后重新开一个终端让变量生效再启动工具。4.4 验证请求真的走对了地方配好之后怎么确认请求没打到官方服务最直接的办法是看端点那边的日志。LM Studio 有请求日志面板第三方服务商后台也有调用记录。你发一条消息端点日志里应该立刻出现对应的请求。如果端点日志没动静但工具显示正在思考那说明请求发到别处去了——大概率是环境变量没生效或者工具读的是另一个配置文件。这时候用env | grep -i base_url检查一下当前终端的环境变量。5. 那些让人抓狂的报错与排查链路5.1 organization has disabled claude subscription access这个报错的意思是工具尝试用你的官方账号鉴权但组织层面把 Claude Code 的订阅访问关了。这不是配置错误是权限问题。遇到这个有两条路。一是找组织管理员开权限但这通常不现实。二是彻底绕开官方鉴权走自己的端点。走第二条路时要确保工具不会再去尝试官方登录。有些工具会在启动时先做一次账号检查检查失败就退出根本不给你走自定义端点的机会。这种情况下需要找到跳过登录检查的配置项或者用代理层在更底层拦截。5.2 model is not supported 的三种可能the gpt-5.6-sol model is not supported when using codex with a...这个报错我遇到过三种成因第一种模型映射没配。工具请求gpt-5.6-sol端点不认识直接拒绝。解法是加map_to。第二种映射配了但没生效。可能是配置文件路径不对工具读的是另一份配置。检查配置文件的加载顺序和优先级。第三种端点确实不支持这个模型且映射目标也写错了。比如你把gpt-5.6-sol映射到了一个端点也不支持的模型名。回到 4.1 节用 curl 确认端点到底支持哪些模型。排查顺序建议是先 curl 端点确认模型名再检查配置文件是否被正确加载最后检查映射字段拼写。5.3 local proxy failed while handling codex endpoint /responses这个报错我在 3.3 节提过根因是路径和协议不匹配。完整的排查链路是这样的第一步确认代理层是否在运行。curl http://127.0.0.1:代理端口/看有没有响应。第二步确认代理层是否认识/responses这个路径。看代理的日志如果日志里显示收到了/responses请求但处理失败说明路径识别没问题是转换逻辑的问题。第三步确认转换后的请求格式对不对。把代理转发出去的请求抓出来看对比端点期望的格式。这一步可能需要代理层开 debug 日志。第四步如果代理层根本不支持/responses那就得换一个支持的工具或者自己写转换逻辑。提示这类协议转换问题抓包是最有效的排查手段。在代理层加一行日志把收到的请求体和转发出去的请求体都打出来对比一下就知道哪里对不上了。5.4 环境变量不生效的隐蔽原因有次我配好了OPENAI_BASE_URL工具却还是走官方端点。查了半天发现我在.zshrc里设了变量但当前终端是用bash开的读的是.bashrc。两个 shell 的配置文件不一样变量自然不生效。这个坑的通用解法是设完环境变量后用echo $OPENAI_BASE_URL确认当前终端能读到。读不到就说明设错了地方。另外IDE 内置的终端有时不继承系统环境变量需要在 IDE 的设置里单独配。6. 让配置更稳的几个实战习惯6.1 配置文件分环境管理我现在的做法是把openrig配置分成local.yaml、remote.yaml两份本地模型用一份第三方服务用另一份。切换时改一下active字段或者用环境变量指定读哪份。export OPENRIG_CONFIG./configs/local.yaml这样做的最大好处是本地调试和线上使用互不干扰。本地那份可以随便改不怕影响正常使用。6.2 密钥永远走环境变量前面提过一次这里再强调。配置文件里写${DEEPSEEK_API_KEY}实际值放在环境变量或.env文件里.env加进.gitignore。这是基本的安全习惯但每年还是能看到有人把密钥提交到公开仓库。# .env 文件 DEEPSEEK_API_KEYsk-xxxxxxxx # 启动时加载 export $(cat .env | xargs)6.3 保留一份最小可用配置折腾过程中配置会越改越复杂。这时候留一份最小可用配置很有必要——只有最基本的端点、密钥、模型映射其他全砍掉。当复杂配置出问题时用最小配置验证端点本身是否正常能快速定位问题是出在端点还是出在配置的某个高级特性上。6.4 关注工具的版本更新Claude Code 和 Codex 都在快速迭代端点路径、鉴权方式、配置字段都可能变。今天能用的配置下个版本可能就失效了。我的习惯是每次升级工具后先用最小配置跑一遍确认基础链路没断再去用复杂配置。热搜里claude code官方文档链接、codex官网下载这些词说明大家都在找权威信息源。我的建议是配置类的问题优先看官方文档的自定义端点或企业部署章节那里通常有最准确的字段说明。社区方案可以参考但要以官方文档为准。7. 关于本地模型接入的一点个人体会用 LM Studio 起本地模型接 Claude Code是我最近用得比较多的组合。好处是数据不出本机坏处是对硬件有要求。7B 级别的模型在普通笔记本上能跑但响应速度一般更大的模型需要显存足够的显卡。实测下来本地模型接进来之后Claude Code 的交互体验和官方版本有明显差异。官方模型在代码理解和长上下文处理上更稳本地模型在简单任务上够用复杂重构就容易跑偏。所以我的用法是日常小改动用本地模型复杂的架构级任务还是切回能力更强的端点。这个组合最大的价值不在于省钱而在于可控。端点在自己手里请求发到哪、发什么内容都清清楚楚。对于有数据合规要求的场景这一点比模型能力本身更重要。配置这件事说到底就是让请求去到该去的地方。openrig也好cc switch也好都是这个目标下的不同实现。把端点、路径、模型映射这三件事理清楚大部分报错都能自己解决。剩下的就是多试、多看日志、多留一份能用的备份配置。