★ FEATURED ARTICLE 1. 从openrig这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的不是某个具体产品而是一种很典型的命名思路——open代表开放、可扩展、可自托管rig在英文里是装配、搭台子的意思比如一台矿机、一套实验装置、一套测试台架都可以叫 rig。把这两个词拼在一起基本能猜到它的定位一套开放的、可自行组装的工具台架用来把若干独立的命令行工具、模型服务、配置系统装配成一条能跑起来的工作流。结合热搜词里高频出现的 Claude Code、Codex、YAML、npm 这几个关键词我判断 openrig 这类项目大概率落在这样一个场景里你手头有一堆 AI 编程助手类的 CLI 工具Claude Code、Codex CLI 等它们各自有各自的配置方式、各自的模型接入方式、各自的启动参数你想把它们统一管理起来用一份 YAML 描述清楚我要用哪个工具、接哪个模型、走哪个端点、用哪套环境变量然后一条命令把整套环境拉起来。这就是rig的含义——不是单个工具而是把工具装配成台架。为什么这个需求真实存在因为现在这类 CLI 工具的生态非常碎片化。Claude Code 有自己的配置目录和订阅校验逻辑Codex CLI 有自己的登录态和 endpoint 处理逻辑你想让它们都指向本地模型服务比如 LM Studio 起的本地推理端点就得分别改各自的配置。改一处忘一处就会出现热搜里那种典型报错——cc switch local proxy failed while handling codex endpoint /responses本质上是代理层在转发 Codex 的/responses请求时配置没对齐请求打到了错误的端点或者带了错误的鉴权头。所以这篇内容我打算这么写不把它当成一个安装教程来写而是当成一次真实的装配过程复盘。我会先讲清楚这类工具台架的核心设计逻辑再讲环境准备里最容易翻车的几个点npm 的 PowerShell 执行策略、镜像源、Node 版本然后是 YAML 配置怎么写才能真正做到一份配置管多个工具接着是本地模型接入和端点转发的坑最后是我自己踩过的几个典型故障的完整排查链路。适合谁看适合已经装过 Claude Code 或 Codex CLI、但被多工具配置管理搞烦了的开发者也适合想自己搭一套统一 AI 编程环境的进阶用户。纯小白也能看但需要你至少会开终端、会改环境变量。2. 装配台架的核心设计逻辑为什么是 YAML npm 这套组合2.1 一份配置管多个工具背后的抽象层次大多数人管多个 CLI 工具的方式是各管各的Claude Code 的配置放它自己的目录Codex 的配置放它自己的目录本地模型的地址在每个工具里各写一遍。这种方式的坏处不是麻烦而是不一致——你改了本地模型的端口得记得去三个地方改你换了一个 API Key得确认每个工具都更新了。一旦漏掉一个报错信息还各不相同排查成本极高。openrig 这类项目要做的抽象是把配置分成两层底层是资源模型服务地址、鉴权信息、代理端点、工作目录。这些是客观存在的东西跟用哪个工具无关。上层是工具绑定Claude Code 用哪个资源、Codex 用哪个资源、各自启动时注入哪些环境变量。YAML 天然适合表达这种两层结构因为它支持嵌套映射和列表可读性又比 JSON 好。你可以在一个文件里写清楚providers模型提供方、tools工具绑定、env环境变量注入三块然后用一个加载器把它们展开成每个工具需要的实际配置。这里有个设计上的关键取舍我要点出来是用 YAML 生成各工具的配置文件还是用环境变量在启动时注入两种做法我都试过。生成配置文件的好处是持久化、工具自己读得到坏处是每次改 YAML 都要重新生成而且会污染工具原本的配置目录出问题不好回滚。环境变量注入的好处是无侵入、临时生效、退出即还原坏处是有些工具不认环境变量只认配置文件。我的经验是优先环境变量实在不行再落盘生成因为无侵入的方案排查起来干净得多。2.2 npm 作为分发层方便但也是坑最多的地方为什么这类工具喜欢用 npm 分发因为目标用户基本都有 Node 环境npm install -g一行就能装跨平台也还行。但 npm 在 Windows 上的坑热搜词里已经暴露得很清楚了npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本npm warn eresolve overriding peer dependencynpm 国内源、npm 镜像源地址第一条是最经典的。PowerShell 默认的执行策略是Restricted不允许运行任何脚本文件而 npm 在 Windows 上会生成一个npm.ps1包装脚本于是你在 PowerShell 里敲npm就直接被拦。解决办法不是去改系统策略那会影响全局安全而是用npm.cmd代替npm或者干脆在 CMD 里操作或者只对当前用户放开执行策略# 只对当前用户生效风险最小 Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned第二条eresolve overriding peer dependency是依赖树冲突的警告通常不致命但如果安装直接失败就得加--legacy-peer-deps或者检查 Node 版本。第三条镜像源国内环境基本是必配的否则装包能等到你怀疑人生npm config set registry https://registry.npmmirror.com # 验证 npm config get registry注意镜像源只影响包的下载地址不影响你项目里配置的模型端点。很多人把这两个概念搞混以为换了镜像源本地模型就能连上了其实完全没关系。2.3 Node 版本被严重低估的隐形杀手我见过太多装完了跑不起来的案例最后查出来是 Node 版本不对。这类 CLI 工具通常要求 Node 18 以上有些新版本甚至要求 Node 20。版本低了会出现各种奇怪的语法错误或者依赖加载失败。建议用 nvm 管理多版本# 查看当前版本 node -v # 如果低于 18装一个 LTS nvm install 20 nvm use 20Windows 上用 nvm-windows注意安装时它会问你是否接管已有的 Node 安装选是否则会出现两个 Node 打架的情况。这个细节文档里基本不写但踩过的人都懂。3. 环境准备阶段最容易翻车的五个点3.1 全局包安装位置与 PATH 的隐性错配npm install -g装完之后敲命令提示不是内部或外部命令十有八九是全局 bin 目录没进 PATH。先查全局目录在哪npm config get prefixWindows 上通常是C:\Users\你的用户名\AppData\Roaming\npm这个目录必须加到系统 PATH 里。Linux/macOS 上通常是/usr/local或~/.npm-global对应的bin子目录要在 PATH 里。改完 PATH 一定要重开终端很多人的改了没用其实是当前终端还在用旧的环境变量。3.2 卸载不干净导致的版本混乱热搜里有npm卸载全局包说明不少人遇到过装错了想重来的情况。卸载命令是npm uninstall -g 包名但要注意有些工具会在用户目录留下配置和缓存卸载包不会清掉这些。如果你重装后行为还是旧的去这几个地方看看~/.config/下的工具配置目录~/.cache/下的缓存Windows 上是%APPDATA%和%LOCALAPPDATA%我的习惯是重装前先手动备份再清空配置目录这样能保证是真正的干净重装。3.3 代理与端点配置/responses报错的根因回到热搜里那个报错cc switch local proxy failed while handling codex endpoint /responses。这句话拆开看cc switch 是切换工具local proxy 是本地代理层failed while handling codex endpoint /responses 是处理 Codex 的/responses端点时失败了。Codex 这类工具走的是 OpenAI 风格的 API 路径/responses是它的对话端点。本地代理层的作用是把工具的请求转发到你配置的实际模型服务。报这个错通常是三种原因之一代理层配置的端点路径不对工具请求/responses但代理转发到了/v1/chat/completions路径不匹配。鉴权头没透传或透传错了本地模型服务可能不需要 Key但代理层硬塞了一个或者反过来需要 Key 却没带。模型服务本身没起来代理转发过去连接被拒。排查顺序我建议从后往前先确认模型服务活着curl一下健康检查端点再确认代理层能连通模型服务最后确认工具到代理层这一段。这样能快速定位是哪一段断了。3.4 本地模型服务的接入姿势热搜里claude code 调用 lmstudio 的本地模型是个高频需求。LM Studio 默认在http://localhost:1234/v1提供 OpenAI 兼容接口。接入的关键是确认它暴露的路径前缀——有的版本是/v1有的直接是根路径。用 curl 验证curl http://localhost:1234/v1/models能返回模型列表说明服务正常。然后在工具的配置里把 base URL 指向这个地址模型名填 LM Studio 里加载的那个模型的标识符不是文件名是 API 返回的id字段。这一步填错模型名报错往往是model not found跟端点错误长得不一样可以据此区分。3.5 订阅校验类报错的应对思路热搜里有一条your organization has disabled claude subscription access for claude code这是账号层面的订阅策略限制不是技术配置问题。遇到这类报错配置层面怎么改都没用得从账号权限或者换用其他接入方式比如指向本地模型或第三方兼容端点来解决。我的建议是在搭台架之前先确认每个工具的接入方式是走官方订阅还是走自定义端点这决定了你后面配置的整个方向。走自定义端点的话订阅校验这一层就绕开了配置自由度反而更高。4. YAML 配置实战从零写一份能跑的多工具配置4.1 YAML 基础语法里最容易写错的三个地方热搜里yolov10 yaml文件怎么创建rstudio的yaml在哪里说明很多人对 YAML 的语法细节不熟。YAML 看着简单但缩进敏感、冒号后要空格、列表符号要顶格这三条是新手翻车重灾区。# 正确示例 providers: - name: local-lmstudio base_url: http://localhost:1234/v1 api_key: not-needed models: - qwen2.5-coder - llama-3.1-8b tools: claude-code: provider: local-lmstudio model: qwen2.5-coder codex: provider: local-lmstudio model: llama-3.1-8b几个要点冒号后面必须有一个空格name:local是错的name: local才对。缩进只能用空格不能用 Tab。这是 YAML 的铁律混用 Tab 会直接解析失败。字符串里的特殊字符比如 URL 里的冒号建议加引号避免被解析成映射。4.2 用锚点和引用消除重复配置多工具配置最大的问题是重复。如果三个工具都指向同一个本地模型服务你不想把 base_url 写三遍。YAML 的锚点和引用*就是干这个的defaults: local_defaults base_url: http://localhost:1234/v1 api_key: not-needed timeout: 120 providers: fast: : *local_defaults model: qwen2.5-coder heavy: : *local_defaults model: llama-3.1-70b:是合并键把锚点里的内容合并进来再覆盖或追加自己的字段。这样改一处 base_url所有引用它的 provider 全跟着变。这个技巧在配置多个环境开发/测试/生产时特别有用。4.3 环境变量注入让配置和密钥分离把 API Key 直接写进 YAML 是不安全的尤其是你要把配置提交到 Git 的时候。正确做法是 YAML 里写占位符运行时从环境变量读providers: remote: base_url: ${REMOTE_BASE_URL} api_key: ${REMOTE_API_KEY}然后在启动脚本里 export 这些变量或者用一个.env文件配合加载器。这样 YAML 可以放心提交密钥留在本地环境里。注意不同工具对环境变量的读取时机不一样有的在启动时读一次有的每次请求都读改完环境变量最好重启工具。4.4 配置校验别等运行时报错才发现写错了YAML 写错了最怕的是工具启动到一半才报错。我的做法是在加载配置前先做一次 schema 校验。可以用 JSON Schema 定义你的配置结构然后用 ajv 之类的库校验。简单一点的做法是写个脚本检查必填字段是否存在、URL 格式是否合法import yaml, sys from urllib.parse import urlparse with open(openrig.yaml) as f: cfg yaml.safe_load(f) for name, p in cfg.get(providers, {}).items(): url p.get(base_url, ) if not urlparse(url).scheme: print(fprovider {name} 的 base_url 不合法: {url}) sys.exit(1) print(配置校验通过)这个脚本不到 15 行但能帮你挡掉 80% 的低级配置错误。养成改完配置先跑校验的习惯比事后排查省太多时间。5. 多工具协同时的端点转发与故障排查链路5.1 为什么需要代理层统一入口的价值当你有 Claude Code、Codex CLI 两个工具各自要接不同的模型直接让它们各自连模型服务行不行行但有两个问题一是每个工具都要单独配端点二是你想做请求日志、限流、格式转换时无处下手。代理层的价值就在于把所有工具的请求收敛到一个入口在这里统一做鉴权、路由、日志、格式适配。代理层的路由逻辑通常是按路径前缀分发/claude/*转发到 Claude 用的模型/codex/*转发到 Codex 用的模型。这样工具侧只需要把 base URL 指向代理具体路由由代理决定。热搜里那个/responses报错就是路由规则没覆盖到这个路径导致的。5.2 一次完整的排查链路复盘我遇到过一次典型的工具连不上故障完整排查过程是这样的第一步确认现象。Claude Code 启动后发消息报连接错误。Codex 同样报错。两个工具都挂说明问题大概率在公共部分——代理层或模型服务。第二步绕过工具直接测代理。用 curl 打代理的健康检查端点curl -v http://localhost:8080/health返回 200代理活着。第三步测代理到模型服务这一段。看代理日志发现转发到模型服务时连接被拒。curl 直接打模型服务curl http://localhost:1234/v1/models连接被拒。到这里定位清楚了模型服务没起来。第四步确认模型服务状态。发现 LM Studio 的进程还在但监听端口变了重启后默认端口可能变。改回配置里的端口或者把配置改成实际端口问题解决。这个链路的价值在于逐段隔离工具→代理→模型三段分别验证哪段断了立刻能看出来。最忌讳的是盯着工具的报错信息反复改工具配置而报错其实来自下游。5.3 常见报错与对应根因对照报错关键词大概率根因优先排查方向failed while handling endpoint /responses代理路由未覆盖该路径检查代理路由规则model not found模型名与 API 返回的 id 不一致curl/models核对 idconnection refused下游服务未启动或端口不对逐段 curl 验证401 / 403鉴权头缺失或错误检查 api_key 注入npm.ps1 禁止运行脚本PowerShell 执行策略改 CurrentUser 策略或用 cmderesolve peer dependency依赖树冲突加--legacy-peer-deps这张表我建议存下来遇到报错先对号入座能省掉大量瞎试的时间。5.4 日志排查的地基代理层一定要开请求日志至少记录请求路径、目标端点、响应状态码、耗时。没有日志的代理层等于黑盒出问题只能靠猜。日志级别建议平时开 info排查时临时开 debug。注意日志里不要打印完整的鉴权头避免密钥泄露。6. 我踩过的坑和几条压箱底的经验6.1 配置文件编码问题Windows 上用记事本编辑 YAML保存时可能带上 BOM 头导致解析器报unexpected character。用 VS Code 编辑右下角确认编码是 UTF-8不带 BOM。这个坑很隐蔽因为文件看着完全正常但解析就是失败。6.2 端口占用与幽灵进程本地模型服务、代理层、工具本身都可能占端口。改配置前先确认端口没被占# Windows netstat -ano | findstr :1234 # Linux/macOS lsof -i :1234有时候你以为服务停了其实进程还在后台跑着占端口新服务起不来。这种幽灵进程在反复调试时特别常见。6.3 版本锁定别让自动更新毁掉你的台架这类工具更新频繁今天能跑的配置明天可能因为工具升级就挂了。我的做法是在项目里记录每个工具的版本号必要时锁定版本npm install -g 包名1.2.3升级前先在测试环境验证别直接在生产台架上升。这个习惯能帮你避免睡一觉起来环境全崩的惨剧。6.4 配置即代码把台架纳入版本管理把 YAML 配置、启动脚本、校验脚本一起放进 Git 仓库每次改动都有记录。这样出问题能快速回滚到上一个可用版本也能清楚看到是哪次改动引入的故障。密钥用环境变量或.env记得加进.gitignore配置本身可以放心提交。6.5 一个实用的小技巧健康检查脚本写一个一键健康检查脚本把工具→代理→模型三段都测一遍输出每段的状态。每次改完配置先跑一遍比手动 curl 快得多#!/bin/bash echo 检查模型服务... curl -s -o /dev/null -w %{http_code}\n http://localhost:1234/v1/models echo 检查代理层... curl -s -o /dev/null -w %{http_code}\n http://localhost:8080/health echo 检查工具... claude-code --version codex --version这个脚本我放在项目根目录改配置后第一件事就是跑它。三段全绿再开始用能挡掉绝大多数改了配置忘了重启服务的低级问题。搭这类台架本质上是在做配置的收敛和故障的隔离。工具越多越需要一个统一的入口和一份清晰的配置。openrig 这个名字背后的思路——开放、可装配——其实适用于任何多工具协同的场景。把配置写清楚、把日志开起来、把排查链路理顺剩下的就是熟能生巧的事了。
阅读完成 · 觉得有帮助？
