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_URLCodex 认OPENAI_BASE_URLLM 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 或 TOMLJSON 不支持注释你没法在配置里写这行是给 DeepSeek 用的别删TOML 虽然好但嵌套结构写起来啰嗦。YAML 的锚点anchor和引用alias机制特别适合这种场景——你可以定义一个base_url锚点让 Claude Code 和 Codex 的配置都引用它改一处全生效。这也是为什么热词里yolov10 yaml文件怎么创建、rstudio的yaml在哪里这类问题频繁出现YAML 已经成了配置领域的事实标准。2.2 npm 作为分发通道一次安装全局可用openrig 选择 npm 分发不是偶然。目标用户群体——用 Claude Code、Codex 的人——大概率已经装了 Node.jsnpm 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 CodeAnthropic Messages/v1/messagesLM Studio、DeepSeekCodex CLIOpenAI Responses/responsesOpenAI、兼容端点LM StudioOpenAI Chat/v1/chat/completions本地模型DeepSeekOpenAI 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_MODELdeepseek_cloud openrig run claude就行。环境变量的命名规则是OPENRIG_工具名_字段名全大写。这个约定要记住排查时用env | grep OPENRIG能一眼看出哪些变量被设置了。提示YAML 对缩进极其敏感用空格不用 Tab。一个 Tab 混进去解析器报的错往往指向完全无关的行号能让你 debug 半小时。建议编辑器开启显示空白字符。4. 实操过程从零到跑通 Claude Code 与 Codex4.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装 openrignpm 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 放进环境变量而不是 YAMLexport 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_URLhttp://127.0.0.1:8787/claudeCodex 则设置export OPENAI_BASE_URLhttp://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 RemoteSignedyour organization has disabled claude subscription access账号订阅权限问题检查账号状态与 openrig 无关codex无法加载组织设置配置文件路径或权限确认~/.codex/目录可读写端点可达但请求超时代理端口被占用或防火墙换端口检查proxy_port5.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 这一层长期看能省下大量重复劳动。 openrig 配置指南：统一管理 Claude Code 与 Codex 的 AI 编码工具链
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_URLCodex 认OPENAI_BASE_URLLM 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 或 TOMLJSON 不支持注释你没法在配置里写这行是给 DeepSeek 用的别删TOML 虽然好但嵌套结构写起来啰嗦。YAML 的锚点anchor和引用alias机制特别适合这种场景——你可以定义一个base_url锚点让 Claude Code 和 Codex 的配置都引用它改一处全生效。这也是为什么热词里yolov10 yaml文件怎么创建、rstudio的yaml在哪里这类问题频繁出现YAML 已经成了配置领域的事实标准。2.2 npm 作为分发通道一次安装全局可用openrig 选择 npm 分发不是偶然。目标用户群体——用 Claude Code、Codex 的人——大概率已经装了 Node.jsnpm 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 CodeAnthropic Messages/v1/messagesLM Studio、DeepSeekCodex CLIOpenAI Responses/responsesOpenAI、兼容端点LM StudioOpenAI Chat/v1/chat/completions本地模型DeepSeekOpenAI 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_MODELdeepseek_cloud openrig run claude就行。环境变量的命名规则是OPENRIG_工具名_字段名全大写。这个约定要记住排查时用env | grep OPENRIG能一眼看出哪些变量被设置了。提示YAML 对缩进极其敏感用空格不用 Tab。一个 Tab 混进去解析器报的错往往指向完全无关的行号能让你 debug 半小时。建议编辑器开启显示空白字符。4. 实操过程从零到跑通 Claude Code 与 Codex4.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装 openrignpm 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 放进环境变量而不是 YAMLexport 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_URLhttp://127.0.0.1:8787/claudeCodex 则设置export OPENAI_BASE_URLhttp://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 RemoteSignedyour organization has disabled claude subscription access账号订阅权限问题检查账号状态与 openrig 无关codex无法加载组织设置配置文件路径或权限确认~/.codex/目录可读写端点可达但请求超时代理端口被占用或防火墙换端口检查proxy_port5.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 这一层长期看能省下大量重复劳动。