1. 从 openrig 说起：一个被低估的 AI 编码工具配置层
第一次看到openrig这个名字，我下意识以为是某个开源钻机项目——毕竟 rig 在工业领域就是钻井平台的意思。直到我在几个 Claude Code 和 Codex 的讨论串里反复撞见它，才意识到这是个跟 AI 编码助手配置管理相关的东西。简单说，openrig 是一套面向 AI 编码工具（Claude Code、Codex CLI 等）的配置编排方案，核心思路是用 YAML 文件把模型接入、工具链、环境变量、代理转发这些零散配置统一收拢，再通过 npm 生态分发和安装。
它解决的问题很具体：当你同时用 Claude Code 写前端、用 Codex 跑后端重构、又想让它们都走本地 LM Studio 或者某个兼容 OpenAI 协议的端点时，每个工具都有自己的配置文件格式、环境变量命名、启动参数。Claude Code 认ANTHROPIC_BASE_URL，Codex 认OPENAI_BASE_URL，LM Studio 又要求/v1后缀，DeepSeek 的接入点还不太一样。手动维护这些配置，改一个忘一个，最后就是cc switch local proxy failed while handling codex endpoint /responses这种报错糊脸。
openrig 适合谁？三类人：一是同时使用多个 AI 编码工具的开发者，二是需要在团队内统一配置、避免每个人重复踩坑的技术负责人，三是想把本地模型（LM Studio、Ollama）接入 Claude Code 或 Codex 的折腾党。哪怕你只是刚装完 npm、还在跟npm.ps1 无法加载文件作斗争，这篇文章里的排查思路和配置模板也能直接抄。
我下面会从设计思路、YAML 配置细节、实操流程、常见报错四个维度拆开讲，尽量把每个"为什么这么配"说清楚，而不是甩一堆命令让你自己猜。
2. 整体设计思路：为什么用 YAML + npm 这套组合
2.1 配置即代码：把散落的参数收进一个文件
AI 编码工具的配置天然是碎片化的。Claude Code 的配置散落在~/.claude/settings.json、环境变量、VS Code 插件设置三处；Codex CLI 有自己的~/.codex/config.toml或者环境变量；如果你还用了 cc switch 这类切换工具，又多一层代理配置。openrig 的第一个设计决策就是用一份 YAML 描述所有工具的接入信息，然后由脚本读取这份 YAML，生成各工具需要的实际配置文件。
为什么选 YAML 而不是 JSON 或 TOML？JSON 不支持注释，你没法在配置里写"这行是给 DeepSeek 用的，别删"；TOML 虽然好，但嵌套结构写起来啰嗦。YAML 的锚点（anchor）和引用（alias）机制特别适合这种场景——你可以定义一个base_url锚点，让 Claude Code 和 Codex 的配置都引用它，改一处全生效。这也是为什么热词里yolov10 yaml文件怎么创建、rstudio的yaml在哪里这类问题频繁出现，YAML 已经成了配置领域的事实标准。
2.2 npm 作为分发通道：一次安装，全局可用
openrig 选择 npm 分发不是偶然。目标用户群体——用 Claude Code、Codex 的人——大概率已经装了 Node.js，npm install -g openrig比让他们去 GitHub 下载二进制、手动加 PATH 要顺手得多。而且 npm 的postinstall钩子可以在安装后自动执行初始化脚本，比如创建默认的~/.openrig/config.yaml、检测已安装的 AI 工具、提示需要补哪些环境变量。
但 npm 也带来了一堆经典问题，热词里那一长串npm : 无法加载文件 d:\program files\nodejs\npm.ps1，因为在此系统上禁止运行脚本就是典型。这是 Windows PowerShell 的执行策略限制，不是 openrig 的锅，但每个 Windows 用户第一次跑 npm 全局命令都会撞上。后面实操部分我会给出具体的解决命令。
2.3 代理层抽象：解决端点不兼容的根因
cc switch local proxy failed while handling codex endpoint /responses这个报错值得单独说。它的本质是：Claude Code 说的是 Anthropic 的 Messages API 协议，Codex 说的是 OpenAI 的 Responses API 协议，而你的本地模型（比如 LM Studio）可能只实现了 OpenAI 的 Chat Completions 协议。三个协议对不上，代理层转发时就会在/responses这个端点上失败。
openrig 的设计里，代理层要做协议转换：把 Claude Code 发来的 Anthropic 格式请求，翻译成目标端点能懂的格式，再把响应翻译回去。这跟单纯的端口转发是两码事。理解这一点，你就能明白为什么有些配置"看起来对但就是不通"——协议没对齐，URL 再对也没用。
| 工具 | 原生协议 | 默认端点路径 | 常见兼容目标 |
|---|---|---|---|
| Claude Code | Anthropic Messages | /v1/messages | LM Studio、DeepSeek |
| Codex CLI | OpenAI Responses | /responses | OpenAI、兼容端点 |
| LM Studio | OpenAI Chat | /v1/chat/completions | 本地模型 |
| DeepSeek | OpenAI Chat | /v1/chat/completions | 云端 API |
这张表建议存下来，排查连接问题时先对照它确认协议层是否匹配。
3. 核心细节解析：YAML 配置结构与关键字段
3.1 配置文件的分层结构
openrig 的配置我习惯分成三层：全局层、工具层、模型层。全局层放通用设置（日志级别、代理端口），工具层放每个 AI 工具的接入参数，模型层定义可复用的模型端点。这样分层的好处是，当你从 LM Studio 切到 DeepSeek 时，只改模型层的一个base_url，工具层不用动。
一个典型的配置骨架长这样：
# ~/.openrig/config.yaml global: proxy_port: 8787 log_level: info models: local_lmstudio: base_url: "http://127.0.0.1:1234/v1" api_key: "lm-studio" protocol: openai_chat deepseek_cloud: base_url: "https://api.deepseek.com/v1" api_key: "${DEEPSEEK_API_KEY}" protocol: openai_chat tools: claude_code: model_ref: local_lmstudio protocol_in: anthropic_messages codex: model_ref: deepseek_cloud protocol_in: openai_responses注意api_key: "${DEEPSEEK_API_KEY}"这种写法，它表示从环境变量读取，不要把密钥硬编码进 YAML。这是配置管理的基本纪律，YAML 文件经常会被提交到 git，明文密钥泄露是高频事故。
3.2 协议字段为什么必须显式声明
很多人配不通的根因就是省略了protocol字段，让工具去猜。openrig 要求显式声明protocol_in（工具发出的协议）和模型的protocol（端点能接受的协议），代理层据此决定是否需要转换。如果两边一致，直接透传；不一致，走转换逻辑。
这里有个容易踩的坑：LM Studio 的/v1端点同时支持 chat completions，但不支持Anthropic 的 messages 格式。所以 Claude Code 接 LM Studio 时，protocol_in: anthropic_messages和protocol: openai_chat必须都写对，代理层才知道要做 Anthropic 到 OpenAI 的转换。少写一个，就是failed while handling endpoint那类报错。
3.3 环境变量注入与优先级
openrig 读取配置时遵循一个优先级链：命令行参数 > 环境变量 > YAML 文件 > 内置默认值。这个顺序很重要，因为它让你可以在不改 YAML 的情况下临时覆盖。比如你想临时把 Claude Code 指向另一个模型，直接OPENRIG_CLAUDE_MODEL=deepseek_cloud openrig run claude就行。
环境变量的命名规则是OPENRIG_<工具名>_<字段名>，全大写。这个约定要记住，排查时用env | grep OPENRIG能一眼看出哪些变量被设置了。
提示：YAML 对缩进极其敏感，用空格不用 Tab。一个 Tab 混进去，解析器报的错往往指向完全无关的行号，能让你 debug 半小时。建议编辑器开启"显示空白字符"。
4. 实操过程：从零到跑通 Claude Code 与 Codex
4.1 环境准备与 npm 安装
先确认 Node.js 版本，openrig 一般要求 18 以上：
node -v npm -v如果npm -v在 Windows PowerShell 里报无法加载文件 npm.ps1，因为在此系统上禁止运行脚本，这是执行策略问题，用管理员身份打开 PowerShell 执行：
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned然后确认。这一步只做一次，之后 npm 全局命令就正常了。如果你在国内，装之前先把源换成国内镜像，能省掉大量超时：
npm config set registry https://registry.npmmirror.com装 openrig：
npm install -g openrig openrig --version如果openrig命令找不到，检查 npm 全局 bin 目录是否在 PATH 里。npm config get prefix会告诉你全局安装位置，把这个路径下的 bin 目录加进系统 PATH 即可。这是npm环境变量path配置那个热词对应的经典问题。
4.2 初始化配置与模型接入
首次运行openrig init会生成默认配置。然后编辑~/.openrig/config.yaml，按上一节的结构填入你的模型端点。以接入本地 LM Studio 为例，先在 LM Studio 里启动服务，确认http://127.0.0.1:1234/v1/models能返回模型列表，再写进配置。
接入 DeepSeek 的话，把 API key 放进环境变量而不是 YAML：
export DEEPSEEK_API_KEY="你的密钥"Windows 用setx DEEPSEEK_API_KEY "你的密钥"，然后重开终端。配置写好后跑一次校验：
openrig validate它会检查 YAML 语法、端点可达性、协议字段完整性。这一步能提前拦掉大部分低级错误。
4.3 启动代理并验证协议转换
openrig proxy start代理默认监听 8787。验证它是否正常工作，直接 curl 一下：
curl http://127.0.0.1:8787/health返回ok说明代理活着。然后让 Claude Code 走这个代理，设置环境变量：
export ANTHROPIC_BASE_URL="http://127.0.0.1:8787/claude"Codex 则设置：
export OPENAI_BASE_URL="http://127.0.0.1:8787/codex"注意路径后缀/claude和/codex是分开的，代理层根据这个前缀判断该用哪套协议转换逻辑。这就是为什么不能简单地把两个工具指向同一个裸地址——协议入口必须区分。
4.4 在 VS Code 里配置 Claude Code
如果你用claude code for vs code插件，配置入口在插件设置里。搜索claude，找到 base URL 相关字段，填http://127.0.0.1:8787/claude。有些版本插件会读环境变量，那就确保 VS Code 是从已经设置了ANTHROPIC_BASE_URL的终端启动的，否则插件进程读不到。
Ubuntu 下配置逻辑一样，只是环境变量写进~/.bashrc或~/.zshrc，然后source一下。macOS 用户注意，GUI 启动的应用不读 shell 的 rc 文件，得用launchctl setenv或者直接在插件设置里填。
5. 常见问题与排查技巧实录
5.1 报错速查表
| 报错信息 | 根因 | 解决方向 |
|---|---|---|
cc switch local proxy failed while handling codex endpoint /responses | 协议不匹配，Codex 发 Responses 格式但端点只认 Chat | 检查protocol_in与protocol字段 |
npm.ps1 无法加载文件，禁止运行脚本 | PowerShell 执行策略 | Set-ExecutionPolicy RemoteSigned |
your organization has disabled claude subscription access | 账号订阅权限问题 | 检查账号状态，与 openrig 无关 |
codex无法加载组织设置 | 配置文件路径或权限 | 确认~/.codex/目录可读写 |
| 端点可达但请求超时 | 代理端口被占用或防火墙 | 换端口，检查proxy_port |
5.2 三个我踩过的坑
第一个坑：YAML 里的 URL 带了尾斜杠。http://127.0.0.1:1234/v1/和http://127.0.0.1:1234/v1在某些拼接逻辑下会变成/v1//chat/completions，双斜杠导致 404。统一不带尾斜杠，能省很多事。
第二个坑：环境变量没生效。在终端里export了，但 Claude Code 是从桌面图标启动的，读不到。解决办法是把变量写进系统级配置，或者从终端启动工具。这个坑在 Windows 上尤其常见。
第三个坑：本地模型上下文长度不够。LM Studio 默认加载的模型可能只有 4K 上下文，Claude Code 发过去的 prompt 动辄上万 token，直接被截断或报错。在 LM Studio 里把 context length 调到 32K 以上，问题消失。这不是 openrig 的问题，但排查时容易误判成配置错误。
5.3 排查的通用顺序
遇到连不通，按这个顺序走：先openrig validate看配置层，再curl端点看网络层，再curl代理的 health 看代理层，最后看工具本身的日志。逐层排除，比一上来就改配置高效得多。工具日志一般在~/.openrig/logs/下，log_level调到debug能看到完整的请求转发记录，包括协议转换前后的 payload，对照着看就能定位是哪一层出的问题。
6. 关于 openrig 后续可以怎么用
配置跑通之后，我实际用下来觉得最省事的一点是：把~/.openrig/config.yaml纳入 dotfiles 仓库管理，换机器时 clone 下来，改一下本机路径和密钥环境变量，所有 AI 工具的接入配置一次性到位。团队协作时，把模型端点定义部分抽出来共享，密钥部分各自维护，既统一又安全。
另外 openrig 的模型层定义可以玩出一些花样，比如给同一个工具配多个模型引用，用环境变量切换，白天用云端模型跑重活，晚上切本地模型省钱。这个切换成本比手动改各工具配置低太多。如果你还在用npm 淘宝源装包、手动改settings.json的阶段，把配置收进 openrig 这一层，长期看能省下大量重复劳动。
