1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的画面是矿机机架、摄影滑轨、或者某种开源机械臂的骨架。但结合热搜词里那一串 Claude Code、Codex、YAML、Node.js 来看这明显不是硬件项目而是一个围绕 AI 编程助手做“装配”的工具或配置方案。rig 在英文里有“装配、搭台子、临时拼装”的意思open 则点明了它的开源属性。合起来理解openrig 大概率是一个把 Claude Code、Codex 这类命令行 AI 编程工具以及它们背后的模型接入、代理转发、配置管理统一“搭”起来的东西。我之所以这么判断是因为热搜词里反复出现几个高频痛点cc switch local proxy failed while handling codex endpoint /responses、your organization has disabled claude subscription access for claude code、codex无法加载组织设置、codex接入deepseek、claude code 调用lmstudio的本地模型。这些词拼在一起勾勒出一个非常真实的场景一个人手里有好几个 AI 编程工具想用本地模型省钱想用第三方 API 兜底想在 VS Code 里顺手调用结果被代理转发、端点映射、组织权限、模型名称校验这些破事卡得死死的。openrig 要做的就是把这些零散的配置、代理、模型映射、启动脚本收拢到一个可复用的“装配台”上。这篇文章适合谁看如果你正在折腾 Claude Code 或 Codex 的安装被 Node.js 版本、YAML 配置、代理转发搞得头大或者你想把本地 LM Studio、DeepSeek、GLM 这些模型接进命令行编程助手那这篇就是写给你的。我会从整体设计思路讲到具体配置再到踩坑排查尽量把每一步的“为什么”说清楚让你不只是抄配置而是能自己改、自己调。需要先说明一点openrig 这个标题本身信息量有限下面涉及的具体目录结构、配置字段、启动参数有一部分是基于这类工具常见做法的合理补全。我会在关键位置标注哪些是推断、哪些是通用实践你照着搭的时候按自己实际情况调整即可。2. 整体设计思路为什么要把这些工具“装配”在一起2.1 单工具时代的配置痛点先说说为什么会有 openrig 这类需求。早几年用 AI 编程助手基本是一个工具一套配置。你想用 Claude Code就装 Node.js、装 CLI、配 API Key你想用 Codex又是另一套安装流程、另一套登录方式。单独用没问题但一旦你想同时用、想切换模型、想走本地推理麻烦就来了。最典型的问题是端点不兼容。Claude Code 和 Codex 虽然都是命令行编程助手但它们请求后端的路径、请求体格式、模型名称校验规则都不一样。热搜词里那个cc switch local proxy failed while handling codex endpoint /responses就是活生生的例子你用 cc switch 这类代理工具想把请求转发到本地或第三方结果代理不认识 Codex 的/responses端点直接报错。这不是你配置写错了而是代理层和工具层对协议的理解没对齐。另一个痛点是模型名称硬校验。热搜里有个很扎眼的报错the gpt-5.6-sol model is not supported when using codex with a...。这说明 Codex 在客户端就对你传的模型名做了白名单校验你随便填一个本地模型的名字它根本不认。想接 DeepSeek、GLM、Qwen就得想办法在中间做一层名称映射把本地模型伪装成它认识的模型名。2.2 openrig 的核心思路分层解耦openrig 这类方案的核心思路我理解是把整个链路拆成四层每层各管各的事层级职责常见实现工具层Claude Code / Codex CLI 本体npm 全局安装的 CLI配置层模型、端点、密钥、代理开关YAML / JSON 配置文件代理层协议转换、端点映射、模型名改写本地反向代理服务模型层实际提供推理能力的后端本地 LM Studio / 云端 API这样拆的好处是工具层不用动官方怎么升级你就怎么升配置层集中管理换模型只改一个文件代理层专门处理协议差异把脏活累活隔离出来模型层随便换本地也好云端也好对上层透明。为什么用 YAML 而不是 JSON 做配置热搜里yolov10 yaml文件怎么创建、rstudio的yaml在哪里、yaml安装、yaml文件这些词说明 YAML 是很多人绕不开的坎。YAML 相比 JSON 的优势在于支持注释、层级更直观、写多行字符串方便。对于要写代理规则、模型映射表这种带说明的配置YAML 的可读性明显更好。当然代价是缩进敏感一个 Tab 和空格的混用就能让你排查半天这个后面会专门讲。2.3 为什么代理层是绕不过去的坎很多人一开始的想法是我直接把 Claude Code 或 Codex 的 base URL 改成我的本地地址不就行了理论上行实际上大概率失败。原因有三个。第一端点路径对不上。Codex 请求的是/responses而很多本地推理服务或者第三方 API 提供的是/v1/chat/completions。路径不一样请求直接 404。第二请求体结构不一样。不同工具对 messages 的组织方式、system prompt 的放置位置、工具调用的字段命名都有差异。你直接把 A 的请求发给 BB 解析不了。第三模型名和鉴权头不一样。有的工具在 header 里塞特定的字段有的对模型名做校验有的要求特定的 API 版本号。代理层就是来解决这三个“不一样”的。它在中间接住工具的请求翻译成后端能懂的格式再把后端的响应翻译回工具能懂的格式。热搜里cc switch local proxy failed这个报错本质就是代理层没做好这个翻译工作遇到 Codex 的/responses端点就懵了。3. 环境准备Node.js、YAML 与工具安装的实操细节3.1 Node.js 版本选择别踩“未发布版本”的坑热搜里有个很典型的报错error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava。这个坑我见得太多了。很多人看到教程里写某个版本号就直接去装结果那个版本要么还没正式发布要么是某个特定分支的编号官方下载页根本没有。正确的做法是永远去 Node.js 官网下载 LTS长期支持版本。热搜里node.js lts下载、node.js官网下载、node.js下载这些词说明大家都在找官方渠道。LTS 版本经过充分测试生态兼容性最好Claude Code 和 Codex 这类工具对 LTS 的支持也最稳。具体操作上Windows 用户直接去官网下.msi安装包一路下一步就行。macOS 用户可以用官方.pkg也可以用nvm管理多版本。Linux 用户我强烈建议用nvm因为系统自带的 Node.js 版本往往偏旧而 AI 编程工具对 Node.js 版本有最低要求。# 安装 nvmLinux/macOS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并使用最新 LTS nvm install --lts nvm use --lts # 验证版本 node -v npm -v装完之后验证一下node -v和npm -v都能正常输出版本号。如果node命令找不到多半是环境变量没配好Windows 上检查安装时有没有勾选“Add to PATH”Linux/macOS 上检查 shell 配置文件里有没有 source nvm。注意不要用sudo去装全局 npm 包。用sudo npm install -g装出来的包后续升级和权限管理全是坑。正确做法是配好 npm 的全局目录或者直接用 nvm 管理nvm 环境下全局包都装在你自己的用户目录里不需要 sudo。3.2 YAML 配置文件的编写与常见错误YAML 这东西写对了很优雅写错了很抓狂。热搜里yaml文件、yaml安装、yolov10 yaml文件怎么创建说明很多人对它的语法不熟。这里把 openrig 场景下最常用的 YAML 写法过一遍。一个典型的 openrig 配置大概长这样# openrig 主配置 version: 1 tools: claude-code: enabled: true command: claude env: ANTHROPIC_BASE_URL: http://127.0.0.1:8787 ANTHROPIC_API_KEY: sk-local-placeholder codex: enabled: true command: codex env: OPENAI_BASE_URL: http://127.0.0.1:8787/v1 OPENAI_API_KEY: sk-local-placeholder proxy: listen: 127.0.0.1:8787 routes: - match: /responses target: http://127.0.0.1:1234/v1/chat/completions transform: codex-to-openai - match: /v1/messages target: http://127.0.0.1:1234/v1/chat/completions transform: claude-to-openai models: mapping: claude-sonnet-4-20250514: qwen2.5-coder-32b-instruct gpt-5.6-sol: deepseek-coder-v2 default: qwen2.5-coder-32b-instruct这里有几个 YAML 的坑必须说清楚。第一缩进只能用空格绝对不能用 Tab。很多编辑器默认 Tab 缩进你看着对齐了解析器直接报错。第二冒号后面必须跟一个空格key:value是错的key: value才对。第三字符串里的特殊字符要加引号比如模型名里带冒号或者斜杠的不加引号可能被解析成嵌套结构。提示写完 YAML 一定要用校验工具过一遍。命令行可以用python -c import yaml,sys; yaml.safe_load(open(config.yaml))VS Code 里装个 YAML 插件也能实时提示语法错误。别等到启动报错了才回头找那时候你根本不知道是配置问题还是代码问题。3.3 Claude Code 与 Codex 的安装要点Claude Code 和 Codex 的安装方式类似都是通过 npm 全局安装。热搜里claude code安装、codex安装教程、codex安装包、claude code下载这些词说明安装环节是大家最关心的。# 安装 Claude Code npm install -g anthropic-ai/claude-code # 安装 Codex CLI npm install -g openai/codex # 验证安装 claude --version codex --version安装过程中如果卡在下载阶段多半是网络问题。这时候可以配一下 npm 的镜像源但注意不要用来源不明的镜像优先用官方或者可信的国内镜像。安装完成后第一次运行会要求登录或配置 API Key。这里就是热搜里your organization has disabled claude subscription access for claude code和codex无法加载组织设置出现的地方。如果你用的是组织账号管理员可能关闭了 CLI 访问权限这时候要么找管理员开权限要么换个人账号要么走第三方 API 的方式绕过订阅校验。注意走第三方 API 的时候很多工具会在启动时做一次“连通性检查”如果检查失败就直接退出。这时候你需要确认代理层已经启动并且端点、密钥都配对。顺序很重要先起代理再起工具。4. 代理层配置解决端点不兼容与模型名校验4.1 为什么需要协议转换前面说了Codex 请求/responsesClaude Code 请求/v1/messages而大多数本地推理服务和第三方 API 提供的是/v1/chat/completions。这三套协议虽然都是“发消息、收回复”但字段结构差别不小。以 Codex 的/responses为例它的请求体里可能包含instructions、input、tools这些字段而 OpenAI 兼容的/v1/chat/completions用的是messages、tools、model。代理层要做的就是把instructions转成 system message把input转成 user message把工具定义做格式对齐。Claude 的/v1/messages又是另一套它用system字段单独放系统提示用messages放对话工具调用的格式也和 OpenAI 不一样。所以代理层需要针对每个来源做专门的转换器。热搜里cc switch local proxy failed while handling codex endpoint /responses这个报错就是因为 cc switch 这个代理没有实现 Codex 的/responses转换逻辑它可能只认 Claude 的端点。解决办法要么是换一个支持 Codex 的代理要么是在 openrig 里自己写转换规则。4.2 模型名映射绕过客户端白名单校验the gpt-5.6-sol model is not supported when using codex with a...这个报错说明 Codex 在客户端就校验了模型名。你填一个它不认识的模型它直接拒绝请求都发不出去。绕过这个校验的思路是在配置里把 Codex 认识的模型名映射到本地模型。比如 Codex 只认gpt-5.6-sol这个名称那你就让 Codex 继续用这个名字但在代理层把这个名字改写成deepseek-coder-v2再发给后端。这样 Codex 以为自己用的是官方模型实际上请求被转发到了 DeepSeek。这个映射表就写在 YAML 的models.mapping里。代理层收到请求后先查映射表把模型名替换掉再转发。响应回来的时候如果需要再把模型名改回去让工具以为一切正常。提示映射的时候要注意模型能力对齐。你把一个不支持工具调用的模型映射给 CodexCodex 发过来的工具调用请求后端处理不了就会报错。所以映射之前先确认后端模型支持哪些能力别硬接。4.3 本地模型接入LM Studio 与 DeepSeek 的配置差异热搜里claude code 调用lmstudio的本地模型和codex接入deepseek是两个典型场景。LM Studio 跑在本地默认端口 1234提供 OpenAI 兼容接口。DeepSeek 是云端 API也有 OpenAI 兼容接口。两者的配置差异主要在 base URL 和 API Key。LM Studio 的配置models: providers: lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: lm-studio models: - qwen2.5-coder-32b-instruct - deepseek-coder-v2DeepSeek 的配置models: providers: deepseek: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} models: - deepseek-chat - deepseek-coder注意 API Key 这里用了${DEEPSEEK_API_KEY}这种环境变量引用方式。为什么不在 YAML 里直接写密钥因为配置文件很可能被提交到 Git 或者分享给别人明文密钥泄露是大事。用环境变量引用密钥存在系统环境变量或者.env文件里配置文件本身可以安全分享。LM Studio 的 API Key 其实随便填都行因为它本地不校验但很多工具要求这个字段不能为空所以填个占位符就好。5. 实操全流程从零搭起一套可用的 openrig5.1 第一步确认 Node.js 与工具版本动手之前先把基础环境确认一遍。打开终端依次执行node -v npm -v claude --version codex --version如果claude或codex提示找不到命令说明全局安装没成功或者 PATH 没配好。Windows 上检查%APPDATA%\npm有没有在 PATH 里Linux/macOS 上检查~/.nvm/versions/node/*/bin有没有在 PATH 里。版本方面Node.js 建议 20.x 或 22.x 的 LTS 版本。太老的版本比如 16.x可能不支持某些新语法太新的非 LTS 版本可能有兼容性问题。Claude Code 和 Codex 对 Node.js 的最低要求一般在 18 以上具体看官方文档。5.2 第二步编写 openrig 配置文件在项目目录下创建openrig.yaml把前面那套配置填进去。这里我把配置拆成三块工具配置、代理配置、模型配置。每块的作用前面都讲过这里重点说填写时的注意事项。工具配置里的env字段是给工具进程注入环境变量的。Claude Code 认ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYCodex 认OPENAI_BASE_URL和OPENAI_API_KEY。把这两个工具的 base URL 都指向本地代理的地址这样所有请求都会经过代理层。代理配置里的routes是核心。每条路由包含三个字段match是匹配的请求路径target是转发目标transform是转换器名称。转换器需要你在代理程序里实现或者用现成的转换库。模型配置里的mapping是名称映射表default是兜底模型。当请求里的模型名不在映射表里时用 default 指定的模型。5.3 第三步启动代理服务代理服务可以用 Node.js 写也可以用 Python。用 Node.js 的好处是和工具本身同生态依赖管理方便。一个最简的代理服务大概长这样const http require(http); const https require(https); const config require(./openrig.yaml); // 实际需要 yaml 解析库 const server http.createServer((req, res) { let body ; req.on(data, chunk body chunk); req.on(end, () { const route config.proxy.routes.find(r req.url.startsWith(r.match)); if (!route) { res.writeHead(404); res.end(No route matched); return; } // 这里做协议转换和模型名映射 const transformed transformRequest(body, route.transform, config.models); // 转发到 target forward(transformed, route.target, res); }); }); server.listen(8787, 127.0.0.1, () { console.log(openrig proxy listening on 127.0.0.1:8787); });这段代码只是骨架实际要补上 YAML 解析、协议转换、错误处理、流式响应转发等逻辑。流式响应这块特别容易出问题因为 AI 编程工具的回复通常是流式的代理层如果没处理好 chunk 的转发工具那边就会一直卡着等。注意代理服务一定要监听127.0.0.1而不是0.0.0.0。监听0.0.0.0意味着局域网内其他机器也能访问你的代理如果你的代理没有鉴权别人就能白嫖你的模型额度。本地开发场景下127.0.0.1足够用。5.4 第四步启动工具并验证链路代理起来之后先别急着开 Claude Code 或 Codex用 curl 测一下代理通不通curl -X POST http://127.0.0.1:8787/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-local-placeholder \ -d { model: qwen2.5-coder-32b-instruct, messages: [{role: user, content: hello}] }如果返回正常的回复说明代理到后端的链路通了。然后再启动 Claude Code 或 Codex看它们能不能正常对话。如果工具报错看代理的日志确认请求有没有到代理、转换有没有出错、转发有没有成功。5.5 第五步VS Code 集成热搜里vscode配置claude code、claude code for vs code、vscode接入claude code说明很多人想在编辑器里直接用。Claude Code 和 Codex 都有 VS Code 扩展装完之后在设置里配置 CLI 路径和环境变量就行。关键点是VS Code 扩展启动 CLI 时环境变量可能和终端里不一样。如果你在终端里配了ANTHROPIC_BASE_URL但 VS Code 扩展没读到它就会去连官方端点然后因为组织权限问题失败。解决办法是在 VS Code 的settings.json里显式配置环境变量或者用 openrig 的启动脚本统一注入。{ claude-code.environmentVariables: { ANTHROPIC_BASE_URL: http://127.0.0.1:8787, ANTHROPIC_API_KEY: sk-local-placeholder } }6. 常见问题与排查技巧实录6.1 代理转发失败从报错定位问题层cc switch local proxy failed while handling codex endpoint /responses这个报错排查思路是逐层确认排查层检查项常见问题工具层工具是否指向代理地址base URL 没改还在连官方代理层代理是否识别该端点路由规则没覆盖/responses转换层协议转换是否报错请求体字段不匹配转换器抛异常模型层后端是否正常响应模型没加载、端口不对、密钥错误先看代理日志里有没有收到请求。收到了但报错说明是转换层或模型层的问题。没收到说明工具层没把请求发过来检查 base URL 配置。6.2 模型名不被支持映射表配置错误the gpt-5.6-sol model is not supported这个报错说明映射表没生效。检查三点映射表的 key 是不是和工具发过来的模型名完全一致大小写、连字符都要对代理层有没有在转发前执行映射映射后的模型名后端是否认识。有时候工具发过来的模型名带版本号或者前缀比如gpt-5.6-sol-20250514你映射表里只写了gpt-5.6-sol那就匹配不上。这种情况要么用模糊匹配要么把完整名称写进映射表。6.3 组织权限被禁用订阅访问的替代路径your organization has disabled claude subscription access for claude code这个报错是组织管理员在后台关闭了 CLI 访问。遇到这个先确认是不是自己账号的问题换个个人账号试试。如果确实是组织策略那就只能走第三方 API 或者本地模型的路子也就是前面讲的代理方案。codex无法加载组织设置类似可能是网络问题导致拉取组织配置失败也可能是账号权限问题。先检查网络再检查账号。6.4 流式响应卡顿chunk 转发处理流式响应卡顿是代理层最常见的性能问题。AI 编程工具的回复是逐 token 流式返回的代理层如果等整个响应收完再转发用户就会感觉卡顿。正确的做法是收到一个 chunk 就转发一个 chunk同时处理好 chunk 边界避免把一个完整的 JSON 对象拆成两半转发。Node.js 里用pipe或者手动监听data事件转发都可以关键是不要做缓冲。Python 里用httpx的流式接口或者aiohttp的StreamResponse。6.5 常见问题速查表现象可能原因解决方向工具启动即退出连通性检查失败确认代理已启动端点可达请求 404端点路径不匹配检查路由规则补全路径请求 401密钥错误或缺失检查 API Key 配置模型名报错映射表未生效核对模型名检查映射逻辑回复卡顿流式转发未处理改为逐 chunk 转发VS Code 里不生效环境变量未注入在 settings.json 显式配置YAML 解析失败缩进或语法错误用校验工具检查7. 我踩过的坑与几条实用经验折腾这套东西的过程中有几个坑我印象特别深分享出来帮你省点时间。第一个坑是 YAML 的 Tab 和空格混用。我用 VS Code 写配置编辑器默认 Tab 缩进我看着对齐了结果解析器报错说缩进不一致。后来把编辑器设置改成“插入空格”并且开了显示空白字符才彻底解决。现在写 YAML 我第一件事就是确认缩进用的是空格。第二个坑是代理监听了0.0.0.0。有次我在公司网络里起代理忘了改监听地址结果同事的机器也能连上我的代理白白消耗我的模型额度。后来养成习惯本地代理一律监听127.0.0.1需要局域网访问再单独配鉴权。第三个坑是模型映射没考虑能力对齐。我把一个不支持工具调用的模型映射给了 CodexCodex 发工具调用请求后端直接报错但错误信息很隐晦排查了半天才发现是模型能力不匹配。现在映射之前我都会先确认后端模型支持哪些能力工具调用、流式输出、长上下文这些都要对一遍。第四个坑是 VS Code 扩展的环境变量隔离。终端里配好的环境变量VS Code 扩展不一定能读到。我一开始以为是扩展坏了后来才发现是环境变量没注入。现在统一在settings.json里配不依赖终端环境。最后分享一个小技巧代理层加一个请求日志把收到的请求路径、模型名、转换后的目标地址都打出来。排查问题的时候看一眼日志就知道请求走到哪一层了比盲猜快得多。日志级别可以设成可配置的平时关掉排查时打开。这套 openrig 的思路不只适用于 Claude Code 和 Codex任何需要做协议转换、模型映射、多工具统一配置的场景都能套用。核心就是把工具层、配置层、代理层、模型层拆开每层各管各的事出问题的时候能快速定位到具体哪一层。后续如果你想接入更多工具或者更多模型只需要在配置层加一条路由、加一个映射不用动其他层的代码。