1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个开源硬件项目毕竟 rig 这个词在矿机、测试台架、无线电设备里出现频率太高了。但把热词列表扫一遍就明白了——Claude Code、Codex、YAML、Node.js这几个词凑在一起指向的其实是另一件事给 AI 编程助手做配置编排和运行环境管理。说白了openrig 是一套围绕命令行 AI 编程工具主要是 Claude Code 和 Codex 这类 CLI Agent的配置组织方案。它要解决的问题很具体当你同时用着 Claude Code、Codex可能还接了本地模型或者第三方 API每个工具都有自己的配置文件、环境变量、模型映射、端点设置时间一长就是一团乱麻。openrig 的思路是用 YAML 做统一的声明式配置把用哪个模型、走哪个端点、带什么参数这些事从各个工具的私有配置里抽出来集中管理。我为什么这么判断看热词就清楚了。cc switch local proxy failed while handling codex endpoint /responses 这条是典型的代理转发报错说明有人在用中间层把 Claude Code 的请求转发到 Codex 的/responses端点结果失败了。codex 接入 deepseek、claude code 调用 lmstudio 的本地模型、使用 cc switch 接入 deepseek v4、qwen、glm 等模型——这些全是同一个诉求的不同侧面让一个 CLI 工具去调用它原生不支持的模型。而 openrig 就是把这个过程配置化、可复用化的那层胶水。适合谁看三类人。第一类是把 Claude Code 或 Codex 当日常主力工具、但想接自己模型的人第二类是团队里要统一多个人的 AI 编程环境、不想每个人手动配一遍的人第三类是纯粹好奇这套 CLI Agent 底层怎么跑、想自己搭一套转发链路的人。如果你只是偶尔用用网页版这篇可能对你偏重了但了解一下配置思路没坏处。2. 整体设计思路为什么是 YAML 加 Node.js2.1 声明式配置为什么比一堆环境变量强传统做法是每个工具配各的。Claude Code 有自己的 settings 文件Codex 有自己的 config你要接第三方模型就得改环境变量、改 base_url、改模型名。问题在于这些配置散落在不同位置格式还不一样改一处忘一处排查起来全靠记忆。openrig 选择 YAML 作为配置载体这个决策我认为是对的。YAML 的可读性比 JSON 好支持注释层级结构清晰适合表达一个工具下面挂多个模型 provider这种嵌套关系。更重要的是YAML 天然适合做配置模板——你可以写一份基础配置不同项目用不同的 override 文件覆盖这在团队协作里非常实用。举个直观的对比。不用 openrig 的时候你想让 Claude Code 走本地模型大概要这么搞export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYdummy export ANTHROPIC_MODELqwen2.5-coder然后换个项目想用另一个模型又得重新 export 一遍或者写个 shell 脚本切换。用 openrig 的思路就是一份 YAML 里定义好多个 profile切换的时候只改一个字段profiles: local-qwen: provider: lmstudio base_url: http://localhost:1234/v1 model: qwen2.5-coder remote-deepseek: provider: deepseek base_url: https://api.deepseek.com model: deepseek-chat default_profile: local-qwen这个差异看起来小但在实际使用中体验差别很大。前者是每次都要想一下怎么配后者是配置一次之后只管选。2.2 Node.js 在这套体系里扮演什么角色热词里 Node.js 出现频率极高还有 node.js 安装、node.js 官网下载、error installing 24.21.0: node.js v24.21.0 is not yet released 这些。这说明 openrig 的运行依赖 Node.js 环境而且很多人在安装环节就卡住了。为什么是 Node.js 而不是 Python 或 Go我的判断是生态原因。Claude Code 本身就是 Node.js 写的npm 包形式分发Codex CLI 也是 Node 生态各种 cc switch 类的转发工具大概率也是 Node 实现。openrig 作为编排层用 Node.js 能直接复用这些工具的模块不用跨语言调用。另外 Node.js 的npx机制让工具分发变得极其简单一行命令就能跑起来这对降低使用门槛很关键。但 Node.js 也带来了麻烦。热词里那条 error installing 24.21.0: node.js v24.21.0 is not yet released or is not available 就是典型问题——有人指定了一个不存在的版本号去装直接报错。还有 node.js lts 下载、安装 node.js 这些说明版本选择本身就是个坑。我的建议很明确不要追最新版用 LTS。Node.js 的奇数版本是实验性的偶数版本才是稳定线LTS 更是经过长期验证的。当前主流应该是 20.x 或 22.x 的 LTS具体装哪个看你的工具链要求。2.3 转发链路的核心从 CLI 到模型的完整路径理解 openrig 的关键是搞清楚一次请求从你敲下回车到模型返回中间经过了什么。这条链路大概是Claude Code / Codex CLI ↓ (读取 openrig 生成的配置) 本地转发层 (cc switch 类工具) ↓ (协议转换 端点重写) 目标模型 API (DeepSeek / Qwen / GLM / 本地 LM Studio)每一层都有坑。第一层CLI 工具读配置的格式和优先级第二层协议转换——Claude 用的是 Anthropic 的 messages 格式Codex 用的是 OpenAI 的 responses 格式第三方模型大多兼容 OpenAI 的 chat completions 格式这三者之间的字段映射不是一一对应的第三层目标 API 的能力差异比如有的模型不支持 function calling有的不支持流式有的对 system prompt 处理方式不同。openrig 的价值就在于把第一层和第二层的配置固化下来让你不用每次手动处理。热词里 cc switch local proxy failed while handling codex endpoint /responses 这个报错本质就是第二层出了问题——转发工具在处理 Codex 的/responses端点时失败了可能是协议转换没覆盖到也可能是端点路径拼错了。3. 核心细节解析与实操要点3.1 环境准备Node.js 装对版本比装新版本重要先把地基打好。Node.js 的安装我推荐两种方式看你的系统习惯。Windows 用户直接去官网下 LTS 的 msi 安装包双击一路下一步就行。注意安装时勾选 Add to PATH不然后面命令行找不到 node 命令。装完开个新的终端敲node -v和npm -v验证能出版本号就成。macOS 和 Linux 用户我更推荐用版本管理器比如 nvm 或者 fnm。原因很简单不同项目可能要求不同的 Node 版本用 nvm 可以随时切换不用卸载重装。装 nvm 的命令curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完重开终端然后nvm install --lts nvm use --lts这样装的就是最新的 LTS 版本。想确认装了什么nvm ls注意不要用nvm install 24.21.0这种指定具体小版本的方式除非你确认这个版本真实存在。热词里那个报错就是栽在这上面。用--lts让工具自己选最稳。3.2 YAML 配置文件的结构设计openrig 的配置核心是一份 YAML。虽然具体字段名可能因版本而异但结构逻辑是通用的。我按常见实践给你拆一个完整的配置骨架version: 1 # 全局默认所有 profile 继承 defaults: timeout: 120 max_retries: 3 stream: true # 模型提供方定义 providers: lmstudio: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed deepseek: type: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} qwen: type: openai-compatible base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: ${QWEN_API_KEY} # 工具级配置 tools: claude-code: profile: local-qwen extra_env: ANTHROPIC_SMALL_FAST_MODEL: qwen2.5-coder-7b codex: profile: remote-deepseek endpoint_override: /responses # 可切换的 profile profiles: local-qwen: provider: lmstudio model: qwen2.5-coder-32b remote-deepseek: provider: deepseek model: deepseek-chat remote-qwen: provider: qwen model: qwen-max这份配置里有几个设计点值得说。api_key 用环境变量引用。${DEEPSEEK_API_KEY}这种写法让密钥不落在配置文件里配置文件可以进版本库、可以分享给同事密钥各人自己设。这是基本的安全习惯别把 key 硬编码进去。providers 和 profiles 分离。provider 描述怎么连端点、认证方式profile 描述用哪个模型。这样一个 provider 可以挂多个 profile比如 DeepSeek 的 provider 下面可以同时有 deepseek-chat 和 deepseek-coder 两个 profile切换只改 profile 名。tools 段做工具级覆盖。Claude Code 和 Codex 对模型的要求不完全一样比如 Claude Code 会区分主模型和快速模型用于一些轻量任务Codex 可能对端点路径有特殊要求。在 tools 段里针对性地覆盖比在 profile 里塞一堆条件判断干净得多。3.3 端点路径与协议转换的坑这是最容易出问题的地方热词里那条/responses报错就是活生生的例子。Claude Code 默认走的是 Anthropic 的/v1/messages端点请求体是 Anthropic 格式。Codex 走的是 OpenAI 的/v1/responses端点注意不是/v1/chat/completions这是新版 API。而绝大多数第三方模型和本地推理服务兼容的是/v1/chat/completions。所以转发层要做两件事路径重写和格式转换。路径重写好理解就是把/v1/messages或/v1/responses映射到/v1/chat/completions。但格式转换就麻烦了。Anthropic 的 messages 格式里system prompt 是顶层字段OpenAI 的 chat completions 里 system 是 messages 数组里的一条。Anthropic 的 tool use 结构和 OpenAI 的 function calling 结构也不一样。如果转发工具没处理好这些映射模型就会收到格式错误的请求返回一堆莫名其妙的报错。我的实操经验是先用 curl 手动测通链路再上 CLI 工具。比如你想确认 LM Studio 能不能正常响应先这么测curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-coder-32b, messages: [{role: user, content: hello}], stream: false }能正常返回说明模型服务本身没问题。然后再测转发层最后才接 CLI。这样出问题能快速定位是哪一层的锅不用在整条链路上瞎猜。3.4 本地模型和远程 API 的取舍热词里 claude code 调用 lmstudio 的本地模型 和 codex 接入 deepseek 代表了两种典型场景各有各的适用面。本地模型LM Studio、Ollama 这类的优势是隐私和零成本。代码不出本机不用担心数据泄露跑起来不花钱适合高频次的日常补全。劣势是能力上限受硬件限制32B 的模型在消费级显卡上跑速度和效果都比不上云端大模型。而且本地模型的上下文窗口通常较小处理大文件容易截断。远程 APIDeepSeek、Qwen、GLM 这些的优势是能力强、上下文大、速度快。DeepSeek 的代码能力在开源模型里是第一梯队价格也便宜。劣势是要联网、要花钱、代码要发出去。我的建议是混合用。日常的代码补全、简单重构走本地模型省时省钱遇到复杂任务、需要长上下文推理的时候切到远程 API。openrig 的 profile 机制正好支持这种切换改一个字段的事。场景推荐方案理由日常补全、格式化本地小模型延迟低、零成本、隐私好复杂重构、架构设计远程大模型推理能力强、上下文大敏感代码处理本地模型数据不出本机大批量代码生成远程 API速度快、并发好4. 实操过程与核心环节实现4.1 从零搭一套可用的配置假设你现在什么都没装我给你走一遍完整流程。第一步装 Node.js。前面说过了用 LTS 版本装完验证node -v npm -v第二步装 Claude Code 或 Codex。Claude Code 是 npm 包npm install -g anthropic-ai/claude-codeCodex 也是类似的 npm 分发方式具体包名看官方文档。装完敲claude --version或codex --version确认。第三步准备模型服务。如果你用本地模型先把 LM Studio 或 Ollama 跑起来确认端口和模型名。如果用远程 API去对应平台申请 key记下来。第四步写 openrig 配置。在项目根目录或者用户主目录下建一个openrig.yaml按前面 3.2 的结构填。第一次配建议只配一个 profile跑通了再加。第五步生成工具配置。openrig 的作用是把这份 YAML 转换成各个 CLI 工具认识的格式。具体命令看 openrig 的实现通常是openrig apply或者openrig sync之类的。执行完它会去改 Claude Code 的 settings 文件、Codex 的 config 文件或者设置对应的环境变量。第六步验证。启动 Claude Code随便问个问题看它是不是走了你配的模型。如果报错看错误信息指向哪一层。4.2 参数计算上下文窗口和超时怎么定配置里有几个参数需要根据实际情况算不能瞎填。上下文窗口context window。这个值要设成模型实际支持的大小设大了会报错设小了浪费能力。本地模型的话LM Studio 加载模型时会显示实际分配的上下文长度比如 8192 或 32768按这个填。远程 API 看官方文档DeepSeek 通常是 64K 或 128K。超时timeout。这个要算一下。本地模型生成速度大概是每秒 10-30 个 token看硬件如果一次请求要生成 2000 个 token那就是 60-200 秒。所以本地模型的 timeout 至少设 180 秒保险起见 300 秒。远程 API 快得多60-120 秒够了。最大重试max_retries。本地模型偶尔会因为显存问题崩一下重试有意义设 2-3 次。远程 API 如果返回 4xx 错误重试没用所以重试逻辑要区分错误类型——这个通常由转发层处理你只要设个合理的次数就行。并发数。如果你同时开多个 Claude Code 实例要注意本地模型的并发能力。消费级显卡通常只能同时处理 1-2 个请求设多了会排队甚至 OOM。远程 API 一般没这个限制但要注意 rate limit。4.3 实操现场一次完整的切换记录我拿一个真实场景走一遍。假设我平时用 DeepSeek今天要处理一段敏感代码想切到本地模型。先看当前配置openrig status输出会显示当前 active 的 profile 是remote-deepseek。切换openrig use local-qwen这个命令会做几件事更新 openrig 的状态文件重新生成 Claude Code 和 Codex 的配置如果 CLI 工具正在运行可能需要重启才生效。然后验证openrig status确认 active profile 变成local-qwen了。启动 Claude Code问一个只有本地模型知道的问题比如问它当前时间本地模型如果没联网会瞎编远程模型也可能瞎编这个测试不严谨更好的办法是看请求日志。看请求日志是最靠谱的验证方式。LM Studio 的界面里有请求记录能看到 Claude Code 发过来的请求。如果日志里有新请求进来说明链路通了。处理完敏感代码切回去openrig use remote-deepseek整个过程不到 10 秒比手动改环境变量、重启终端快多了。这就是配置化的价值。4.4 团队协作场景下的配置管理一个人用和团队用配置管理的思路不一样。一个人用配置文件放本地就行怎么方便怎么来。团队用就要考虑几个问题配置怎么分发、密钥怎么管理、个人偏好怎么保留。我的做法是分两层。基础配置进版本库包含 providers 定义、profile 定义、工具级设置但不含任何密钥。个人配置放本地用.openrig.local.yaml这种命名被 gitignore 掉里面只放个人的密钥和偏好覆盖。openrig 如果支持配置合并大部分这类工具都支持加载顺序是基础配置 → 个人配置后者覆盖前者。这样新人入职只要 clone 仓库、建个本地配置填上自己的 key就能跑起来不用问东问西。密钥管理还有个进阶做法用系统的密钥管理工具比如 macOS 的 Keychain、Linux 的 secret-tool配置里只写引用。不过这个配置起来麻烦小团队用环境变量就够了。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错error installing 24.21.0: node.js v24.21.0 is not yet released。这个前面说过了指定了不存在的版本。解决方法是别指定具体版本用--lts。如果你确实需要特定版本先去 Node.js 官网的 releases 页面确认这个版本存在。npm 装包卡住或超时。国内网络环境下 npm 默认源可能很慢。换源npm config set registry https://registry.npmmirror.com这个镜像源同步及时速度也快。换完再装。权限错误 EACCES。Linux 和 macOS 上全局装包可能因为权限不够报错。不要用 sudo 硬来正确做法是配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到.bashrc或.zshrc里重开终端生效。5.2 转发链路的排查方法cc switch local proxy failed while handling codex endpoint /responses。这个报错说明转发层在处理 Codex 的/responses端点时挂了。排查步骤确认转发工具是否支持/responses端点。有些老版本只支持/chat/completions遇到/responses直接懵。确认端点路径配置对不对。Codex 可能配置里写的是/responses但转发工具期望的是/v1/responses差个前缀就 404。看转发工具的日志。这类工具一般会打详细日志能看到它收到了什么请求、转发到了哪里、目标返回了什么。请求发出去了但模型没响应。先确认模型服务本身活着curl http://127.0.0.1:1234/v1/models能列出模型列表说明服务正常。然后确认转发层和目标之间的网络通不通本地的话基本没问题远程的话检查防火墙和代理设置。返回内容乱码或格式错误。这通常是协议转换没做好。比如 Claude Code 发的是 Anthropic 格式转发层没转直接透传给 OpenAI 兼容的模型模型看不懂就返回错误。解决方法是确认转发工具支持你用的协议组合或者换个支持更好的转发工具。5.3 模型能力相关的坑模型不支持 function calling。Claude Code 和 Codex 都重度依赖工具调用读文件、执行命令都靠这个。如果你接的模型不支持 function calling工具会退化成纯聊天很多功能用不了。选模型的时候要确认这一点DeepSeek、Qwen 的主流模型都支持一些小的本地模型可能不支持。上下文窗口不够。处理大文件时如果模型上下文窗口小内容会被截断模型看不到完整代码就瞎改。解决办法是换大窗口模型或者用工具的分块处理功能如果有的话。模型对 system prompt 不敏感。有些模型对 system prompt 的遵循度不高Claude Code 精心设计的系统提示词它不当回事行为就会很怪。这个只能靠试不同模型表现差异很大。5.4 常见问题速查表现象可能原因排查方向安装报版本不存在指定了未发布的版本号改用--ltsnpm 装包超时默认源慢换国内镜像源全局装包权限错误目录权限不足配置用户级 prefix转发报端点错误路径不匹配或协议不支持检查端点配置和工具版本模型无响应服务没起来或网络不通curl 测服务检查网络返回格式错误协议转换失败确认转发工具支持该协议组合工具调用失效模型不支持 function calling换支持的工具调用模型大文件处理出错上下文窗口不足换大窗口模型或分块处理5.5 几个我踩过的坑别在配置文件里写死密钥。我见过有人把 API key 直接写进 YAML 然后提交到公开仓库第二天 key 就被盗刷了。用环境变量引用配置文件可以随便分享。切换 profile 后记得重启 CLI。有些 CLI 工具启动时读一次配置就缓存了你中途改配置它不认。切换后重启一下最保险。本地模型的端口别用默认的。LM Studio 默认 1234Ollama 默认 11434这些端口很容易和其他服务冲突。改个不常用的端口比如 18080省得排查半天发现是端口占用。日志级别调高一点。排查问题的时候把转发工具和 CLI 的日志级别都调到 debug能看到完整的请求和响应。虽然日志量大但定位问题快。问题解决后再调回去。版本锁定。Node.js 版本、CLI 工具版本、转发工具版本这三个的兼容性不是随便组合都行的。团队里最好统一版本写进文档避免我这能跑你那不能跑的扯皮。6. 这套东西还能怎么扩展openrig 这套配置编排的思路其实不局限于 Claude Code 和 Codex。任何有配置文件、需要切换后端、需要团队统一的 CLI 工具都能套用类似的模式。比如你同时用多个 AI 辅助工具——代码补全一个、文档生成一个、翻译一个——完全可以用一份 YAML 统一管理它们的模型配置。再比如做模型评测的时候需要频繁切换不同的模型跑同一批任务配置化的切换比手动改环境变量高效太多。我个人的体会是这类工具的价值不在于它本身多复杂而在于它把配置这件事从每次都要想变成了一次配好、随时切换。省下来的心智负担比省下来的时间更值钱。你要是也在用多个 AI 编程工具被配置问题折腾过不妨试试这个思路哪怕不用 openrig自己写个脚本做类似的事体验也会好很多。