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 dependency
• npm 国内源、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 20

Windows 上用 nvm-windows，注意安装时它会问你"是否接管已有的 Node 安装"，选是，否则会出现两个 Node 打架的情况。这个细节文档里基本不写，但踩过的人都懂。

3. 环境准备阶段最容易翻车的五个点

3.1 全局包安装位置与 PATH 的隐性错配

npm install -g装完之后敲命令提示"不是内部或外部命令"，十有八九是全局 bin 目录没进 PATH。先查全局目录在哪：

npm config get prefix

Windows 上通常是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是它的对话端点。本地代理层的作用是把工具的请求转发到你配置的实际模型服务。报这个错，通常是三种原因之一：

1. 代理层配置的端点路径不对：工具请求/responses，但代理转发到了/v1/chat/completions，路径不匹配。
2. 鉴权头没透传或透传错了：本地模型服务可能不需要 Key，但代理层硬塞了一个，或者反过来，需要 Key 却没带。
3. 模型服务本身没起来：代理转发过去连接被拒。

排查顺序我建议从后往前：先确认模型服务活着（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(f"provider {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 常见报错与对应根因对照

这张表我建议存下来，遇到报错先对号入座，能省掉大量瞎试的时间。

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 这个名字背后的思路——开放、可装配——其实适用于任何多工具协同的场景。把配置写清楚、把日志开起来、把排查链路理顺，剩下的就是熟能生巧的事了。