openrig：用YAML统一编排Claude Code与Codex的AI编码环境

openrig：用YAML统一编排Claude Code与Codex的AI编码环境

发布时间：2026/10/4 9:58:59
openrig：用YAML统一编排Claude Code与Codex的AI编码环境 1. 从 openrig 这个标题说起它到底想解决什么问题第一次看到 openrig 这个词我脑子里蹦出来的第一反应是“open”加“rig”的组合。rig 在英文里本意是“装配、搭建一套设备”在工程语境里常指把一堆零散部件组合成一套能跑起来的系统。所以 openrig 从字面上理解就是“开放式的装配方案”——把原本需要手动拼装、配置繁琐的东西用一套公开、可复用的方式固定下来。结合热搜词里高频出现的 Claude Code、Codex、YAML、npm 这几个关键词我基本能判断出 openrig 的定位它大概率是一个围绕 AI 编程助手Claude Code、Codex 这类 CLI 工具的配置装配方案用 YAML 作为描述语言通过 npm 分发帮开发者把多个 AI 编码工具的本地环境、模型接入、代理转发、参数配置统一管理起来。说白了就是解决“我装了三四个 AI 编码工具每个都要单独配一遍配置还互相打架”这个痛点。为什么我这么判断你看热搜词里那些长尾词就明白了“claude code 调用 lmstudio 的本地模型”“codex 接入 deepseek”“cc switch local proxy failed while handling codex endpoint /responses”“vscode 配置 claude code”“ubuntu 配置 claude code”。这些词全部指向同一个场景——开发者想在自己的机器上同时跑多个 AI 编码工具并且希望它们能灵活切换后端模型本地模型、云端模型都行但配置过程极其折腾动不动就报错。openrig 要做的就是把这套折腾过程标准化。它用 YAML 文件描述“我要用哪些工具、每个工具接哪个模型、走什么协议、端口怎么分配”然后通过 npm 安装一个命令行工具一条命令把整套环境装配好。这个思路和 Docker Compose 用 YAML 描述容器编排是一个道理只不过 openrig 编排的是 AI 编码工具的本地运行环境。适合谁来参考三类人最需要第一类是在 Windows 上折腾 Claude Code 和 Codex 安装、被 PowerShell 脚本执行策略卡住的开发者第二类是想让 AI 编码工具接入本地模型比如通过 LM Studio 跑的模型或者第三方模型服务的人第三类是需要频繁在多个 AI 编码工具之间切换、希望有一套统一配置管理的团队。如果你只是偶尔用一下网页版 AI 对话那 openrig 对你价值不大但如果你已经把 AI 编码工具当成日常开发的基础设施那这套东西值得花时间研究。2. openrig 的核心设计思路拆解2.1 为什么用 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置描述语言这个决策背后有很实际的考量。JSON 的问题是写起来太啰嗦每个键都要加引号嵌套深了以后括号对不齐就容易出错而且 JSON 不支持注释你没法在配置里写“这行是干嘛的”。TOML 虽然比 JSON 友好但它在表达嵌套结构时不够直观尤其是当你要描述“多个工具、每个工具有多个模型后端”这种树状结构时TOML 的[table.subtable]语法会让人看花眼。YAML 的优势在于缩进即层级一眼就能看出配置的从属关系支持注释方便标注每个字段的用途支持锚点和引用可以在多个工具配置之间复用公共参数。比如你定义了一个default_model锚点后面每个工具都可以引用它改一处就全改了。这对于 openrig 这种“多个工具共享部分配置”的场景来说是刚需。我实测下来用 YAML 写 openrig 配置的体验确实比 JSON 好很多。一个典型的 openrig 配置文件大概长这样version: 1 tools: claude-code: enabled: true model: local_model provider: lmstudio endpoint: http://127.0.0.1:1234/v1 name: qwen2.5-coder-7b env: ANTHROPIC_BASE_URL: http://127.0.0.1:8080 codex: enabled: true model: *local_model env: OPENAI_BASE_URL: http://127.0.0.1:8080/v1你看local_model定义了一个锚点*local_model引用了它。如果哪天我想把本地模型从 qwen 换成 deepseek只需要改锚点定义那一处两个工具同时生效。这种复用能力是 JSON 给不了的。2.2 npm 作为分发渠道的利与弊openrig 通过 npm 分发这个选择很聪明但也有坑。聪明的地方在于npm 的覆盖面极广几乎每个前端/Node.js 开发者机器上都有 npm安装一条npm install -g openrig就完事不需要额外装包管理器。而且 npm 的版本管理机制成熟可以方便地发布更新、回滚版本。但坑也很明显。热搜词里有一堆关于 npm 的报错“npm : 无法加载文件 d:\program files\nodejs\npm.ps1因为在此系统上禁止运行脚本”“npm warn eresolve overriding peer dependency”“npm 卸载全局包”。这些全是 Windows 上 npm 的经典问题。PowerShell 默认禁止执行脚本导致 npm 的.ps1包装脚本跑不起来全局包安装路径和 PATH 环境变量对不上导致装完了命令找不到peer dependency 冲突导致安装失败。所以 openrig 虽然用 npm 分发但它的文档里必须把 Windows 下的 npm 配置讲清楚否则大量用户会卡在第一步。我个人的经验是在 Windows 上先把 PowerShell 的执行策略改成RemoteSigned命令是Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后确认 npm 的全局安装路径已经加进 PATH。这两步做完后面才谈得上装 openrig。2.3 多工具统一编排的价值在哪里单独装 Claude Code 或者单独装 Codex其实都不算太麻烦。真正麻烦的是“同时装好几个还要让它们共享配置、切换模型”。我举个例子你就明白了。假设你白天用 Claude Code 写业务代码晚上用 Codex 跑一些实验性的重构。Claude Code 默认连的是官方服务Codex 默认连的也是官方服务。但你想让它们都走本地 LM Studio 的模型来省钱或者走某个第三方兼容接口来获得更快的响应。这时候你要分别改两个工具的配置文件而且它们的配置格式还不一样——Claude Code 认ANTHROPIC_BASE_URLCodex 认OPENAI_BASE_URL端口和路径规则也不同。openrig 的价值就在于它把这些差异封装在内部你只需要在 YAML 里声明“我要用本地模型”它自动帮你生成每个工具各自需要的环境变量和配置文件。切换模型的时候改一处 YAML所有工具同步生效。这就是“编排”的意义——把多个异构系统的配置差异抹平对外暴露统一的抽象。3. 核心细节解析与实操要点3.1 环境准备Node.js 与 npm 的正确安装姿势openrig 依赖 Node.js 运行时和 npm 包管理器所以第一步是把这两个装好。这里有个关键选择用官方安装包还是用版本管理工具。我强烈建议用 nvmNode Version Manager来装 Node.js而不是直接下官方安装包。原因很简单openrig 可能对 Node.js 版本有要求用 nvm 可以随时切换版本而且 nvm 装的 Node.js 不会污染系统 PATH卸载也干净。Windows 上用 nvm-windowsmacOS/Linux 上用 nvm。装完之后用nvm install 20装一个 LTS 版本再用nvm use 20切过去。然后验证node -v npm -v如果npm -v报“无法加载文件 npm.ps1因为在此系统上禁止运行脚本”说明 PowerShell 执行策略卡住了。解决办法是在管理员权限的 PowerShell 里执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这个命令的意思是允许当前用户执行本地编写的脚本以及从互联网下载但经过签名的脚本。RemoteSigned比Unrestricted安全比Restricted宽松是开发场景下的推荐值。注意改执行策略之前确认你理解这个操作的含义。如果你在公司受管设备上操作可能需要 IT 部门授权。3.2 npm 国内源配置别让网络拖后腿npm 默认从官方 registry 拉包国内访问速度不稳定。openrig 安装过程中要拉不少依赖如果源不对可能卡半天甚至超时失败。所以装完 Node.js 之后第一件事是配国内镜像源。npm config set registry https://registry.npmmirror.com这个地址是淘宝源的新域名老域名registry.npm.taobao.org已经停止服务了别再用了。配完之后验证一下npm config get registry应该输出https://registry.npmmirror.com/。如果输出还是官方地址说明配置没生效检查一下是不是有.npmrc文件覆盖了全局配置。实操心得有些公司内网有自己的 npm 私有源这种情况下不要盲目改成淘宝源否则可能拉不到公司内部包。先问清楚团队用的什么源。3.3 openrig 的安装与初始化环境准备好之后安装 openrig 本身npm install -g openrig-g表示全局安装这样在任何目录下都能调用openrig命令。装完之后验证openrig --version如果提示“command not found”或者“不是内部或外部命令”说明 npm 全局安装路径没加进 PATH。用npm config get prefix查看全局路径然后把这个路径加进系统环境变量。初始化一个 openrig 项目openrig init这个命令会在当前目录生成一个openrig.yaml模板文件里面包含所有可配置项的注释说明。我建议不要直接改这个模板而是复制一份改成openrig.local.yaml然后在.gitignore里把openrig.local.yaml排除掉。这样你的个人配置不会误提交到团队仓库团队共享的配置放在openrig.yaml里。3.4 YAML 配置文件的字段详解openrig 的 YAML 配置分几个层级全局设置、工具定义、模型后端、代理规则。我逐个拆解。全局设置部分version: 1 log_level: info proxy: enabled: true port: 8080version是配置格式版本openrig 升级后如果配置格式变了靠这个字段做兼容。log_level控制日志详细程度排查问题时可以改成debug。proxy是本地代理开关开启后 openrig 会在本机起一个转发服务所有工具的请求先经过它再由它转发到真正的模型后端。这个设计的好处是工具端只需要认一个固定地址后端模型怎么换都不用改工具配置。工具定义部分tools: claude-code: enabled: true command: claude env: ANTHROPIC_BASE_URL: http://127.0.0.1:8080 ANTHROPIC_API_KEY: dummy-key codex: enabled: true command: codex env: OPENAI_BASE_URL: http://127.0.0.1:8080/v1 OPENAI_API_KEY: dummy-key每个工具下面可以配enabled是否启用、command启动命令、env环境变量。环境变量是核心因为 Claude Code 和 Codex 都是通过环境变量来识别后端地址的。这里把它们的 base URL 都指向 openrig 的本地代理端口 8080API key 填一个占位符就行因为本地代理不校验 key。模型后端部分backends: local-lmstudio: type: openai-compatible endpoint: http://127.0.0.1:1234/v1 model: qwen2.5-coder-7b api_key: not-needed remote-deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 model: deepseek-coder api_key: ${DEEPSEEK_API_KEY}type指定后端协议类型openai-compatible表示这个后端兼容 OpenAI 的接口格式。endpoint是后端地址model是模型名称api_key支持从环境变量读取用${VAR_NAME}语法避免把密钥明文写在配置文件里。代理规则部分routes: - match: /v1/messages backend: local-lmstudio - match: /v1/chat/completions backend: remote-deepseekroutes定义请求路径和后端的映射关系。比如 Claude Code 发的请求路径是/v1/messages就转发到本地 LM StudioCodex 发的请求路径是/v1/chat/completions就转发到远程 DeepSeek。这样两个工具各走各的后端互不干扰。4. 实操过程与核心环节实现4.1 从零搭建一套本地 AI 编码环境我拿一台干净的 Windows 机器做演示完整走一遍流程。第一步装 nvm-windows。去 nvm-windows 的发布页下载安装包装完之后打开新的 PowerShell 窗口执行nvm version确认安装成功。第二步装 Node.js 20nvm install 20 nvm use 20第三步配 npm 国内源npm config set registry https://registry.npmmirror.com第四步解决 PowerShell 脚本执行策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned第五步装 openrignpm install -g openrig第六步初始化配置mkdir my-ai-env cd my-ai-env openrig init第七步编辑openrig.yaml填入你的模型后端信息。如果你本地跑了 LM Studio确认 LM Studio 的 server 已经启动默认端口是 1234。如果你要用远程模型服务把 endpoint 和 api_key 填对。第八步启动 openrigopenrig up这个命令会做几件事启动本地代理服务、根据配置生成各工具的环境变量文件、按需启动工具进程。启动成功后你会看到日志输出显示代理监听在 8080 端口各个工具已就绪。第九步验证。新开一个终端运行claude命令随便问一个问题看是否能正常返回。如果返回了本地模型的回答说明链路通了。4.2 让 Claude Code 接入 LM Studio 本地模型Claude Code 默认连的是官方服务要让它走本地 LM Studio核心是改ANTHROPIC_BASE_URL。但这里有个坑Claude Code 用的 API 格式和 OpenAI 不完全一样它走的是 Anthropic 自己的 Messages API 格式。而 LM Studio 默认暴露的是 OpenAI 兼容接口。所以你不能直接把 Claude Code 指向 LM Studio中间需要一个格式转换层。openrig 的代理就干这个事。它在收到 Claude Code 的/v1/messages请求后把 Anthropic 格式转换成 OpenAI 格式转发给 LM Studio再把 LM Studio 的响应转换回 Anthropic 格式返回给 Claude Code。这个转换逻辑是 openrig 内置的你不需要自己写。配置上你只需要确保tools: claude-code: env: ANTHROPIC_BASE_URL: http://127.0.0.1:8080 backends: local-lmstudio: type: openai-compatible endpoint: http://127.0.0.1:1234/v1 model: qwen2.5-coder-7b routes: - match: /v1/messages backend: local-lmstudio注意事项LM Studio 里要先把模型加载起来并且开启 server 模式。模型选择上编码任务建议用参数量 7B 以上的 coder 类模型太小的模型代码理解能力不够生成质量差。4.3 让 Codex 接入 DeepSeek 远程服务Codex 走的是 OpenAI 兼容接口所以接入 DeepSeek 相对直接。DeepSeek 的 API 地址是https://api.deepseek.com/v1模型名填deepseek-coder。配置tools: codex: env: OPENAI_BASE_URL: http://127.0.0.1:8080/v1 OPENAI_API_KEY: dummy backends: remote-deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 model: deepseek-coder api_key: ${DEEPSEEK_API_KEY} routes: - match: /v1/chat/completions backend: remote-deepseek然后在系统环境变量里设置DEEPSEEK_API_KEY为你申请到的密钥。openrig 启动时会读取这个环境变量注入到后端配置里。实操心得不要把 API key 直接写在 YAML 文件里尤其是如果这个文件要提交到 Git 仓库。用${VAR_NAME}语法从环境变量读取是更安全的做法。Windows 上设置环境变量用setx DEEPSEEK_API_KEY your-key设置完要重开终端才生效。4.4 代理转发失败的排查过程热搜词里有一条“cc switch local proxy failed while handling codex endpoint /responses”这个报错我遇到过。现象是Claude Code 能正常用但 Codex 一发请求就报代理处理失败。排查思路是这样的。首先看 openrig 的日志把log_level改成debug重启 openrig然后复现问题。日志里会显示 Codex 发的请求路径是什么。我发现 Codex 发的路径是/responses而不是我配置里写的/v1/chat/completions。原来 Codex 在某些版本里用的是/responses端点不是标准的 chat completions 端点。解决办法是在 routes 里加一条匹配规则routes: - match: /responses backend: remote-deepseek - match: /v1/chat/completions backend: remote-deepseek或者用通配符routes: - match: /* backend: remote-deepseek但通配符要小心如果多个后端共存通配符可能导致请求被转发到错误的后端。所以更稳妥的做法是明确列出所有可能的路径。这个问题的本质是不同 AI 编码工具用的 API 端点路径不统一有的用/v1/chat/completions有的用/responses有的用/v1/messages。openrig 的 routes 机制就是用来处理这种差异的但前提是你得知道每个工具实际发的是什么路径。不知道的时候开 debug 日志看一看便知。5. 常见问题与排查技巧实录5.1 npm 相关报错速查报错信息原因解决办法npm : 无法加载文件 npm.ps1因为在此系统上禁止运行脚本PowerShell 执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSignednpm warn eresolve overriding peer dependency依赖版本冲突通常不影响功能可忽略若安装失败用--legacy-peer-depscommand not found: openrig全局安装路径未加入 PATHnpm config get prefix查看路径加入系统 PATH安装速度极慢或超时默认源网络不通npm config set registry https://registry.npmmirror.comnpm 卸载全局包失败权限不足Windows 用管理员 PowerShellmacOS/Linux 加sudo5.2 代理转发类问题排查代理转发失败是最常见的问题类型。排查步骤我总结成一套固定流程第一步确认 openrig 代理本身在运行。执行openrig status看代理端口是否监听。如果没监听说明 openrig 没启动成功检查配置文件语法是否正确。第二步确认后端可达。用 curl 直接请求后端地址curl http://127.0.0.1:1234/v1/models如果这个请求失败说明后端本身有问题跟 openrig 无关。先解决后端问题。第三步确认路由匹配。开 debug 日志看请求路径是否被正确匹配到某个 route。如果日志显示“no route matched”说明 routes 配置里缺少对应路径的规则。第四步确认格式转换。如果后端返回了响应但工具端报解析错误可能是格式转换出了问题。这种情况通常出现在 Anthropic 格式和 OpenAI 格式互转的场景检查 openrig 版本是否支持你用的工具版本。避坑技巧openrig 的配置文件改完之后需要重启 openrig 才生效。执行openrig down再openrig up或者openrig restart。我见过有人改完配置直接测试结果一直不生效折腾半天才发现是没重启。5.3 模型接入类问题“claude code 调用 lmstudio 的本地模型”这个场景下最常见的问题是模型返回的响应格式不符合 Claude Code 的预期。Claude Code 期望的响应里有特定的字段结构而某些本地模型通过 OpenAI 兼容接口返回的格式可能有差异。openrig 的转换层会尽量做适配但如果模型本身输出就不规范转换层也救不了。解决办法是换一个指令遵循能力更强的模型。我实测下来Qwen2.5-Coder 系列在格式遵循方面表现比较稳DeepSeek-Coder 也不错。一些来路不明的小模型虽然跑得快但输出格式经常跑偏用在 AI 编码工具里会频繁报错。另一个问题是上下文长度。Claude Code 处理大型代码库时请求的 token 数可能很大。如果本地模型的上下文窗口不够请求会被截断或报错。选模型的时候注意看它的上下文窗口大小编码场景建议至少 32K最好 128K。5.4 跨平台配置差异Windows、macOS、Linux 三个平台在环境变量设置、路径分隔符、权限管理上都有差异。openrig 尽量做了跨平台适配但有些地方还是需要手动处理。Windows 上环境变量用setx设置路径用反斜杠或正斜杠都行Node.js 会处理。macOS/Linux 上用export设置路径用正斜杠。配置文件里的路径建议统一用正斜杠Node.js 在 Windows 上也能识别正斜杠这样配置文件可以跨平台复用。权限方面macOS/Linux 上全局安装 npm 包可能需要sudo但更好的做法是配置 npm 的全局路径到用户目录避免用sudo。命令是npm config set prefix ~/.npm-global然后把~/.npm-global/bin加进 PATH。这样装全局包不需要 sudo也更安全。6. 我在这套方案上踩过的坑和总结的经验openrig 这套思路我是很认可的但在实际使用中确实有一些文档里不会写的坑。第一个坑是 YAML 的缩进。YAML 对缩进极其敏感用 Tab 还是空格、缩进几个空格都有讲究。我建议统一用两个空格并且在编辑器里开启“显示空白字符”这样能一眼看出缩进是否一致。很多“配置不生效”的问题最后查出来都是缩进错了。第二个坑是端口冲突。openrig 默认用 8080 做代理端口但 8080 是个热门端口很多其他服务也用。如果启动时报“端口已被占用”改 openrig 的代理端口就行在 YAML 里把proxy.port改成其他值比如 18080。同时记得把工具的环境变量里的 base URL 端口也改掉两边要一致。第三个坑是模型切换后的缓存问题。有些 AI 编码工具会缓存上一次的模型响应或会话状态切换后端模型后旧缓存可能导致行为异常。遇到这种情况清掉工具的缓存目录再重启。Claude Code 的缓存在用户目录下的.claude文件夹里Codex 的缓存在.codex文件夹里。第四个坑是 API key 的环境变量读取时机。openrig 在启动时读取环境变量如果你在 openrig 启动后才设置环境变量它读不到。所以顺序是先设环境变量再启动 openrig。Windows 上用setx设置完要重开终端因为setx只对新开的进程生效。最后分享一个我常用的调试技巧当链路出问题时不要一上来就怀疑 openrig先用 curl 直接测后端再用 curl 测 openrig 代理最后再测工具端。一层一层往上排查能快速定位问题出在哪一层。这个思路和网络排查里的“分层诊断”是一个道理比盲目改配置高效得多。这套方案后续还可以扩展的方向是把 openrig 的配置纳入版本管理团队共享一套基础配置每个人用openrig.local.yaml覆盖个人差异。这样新成员入职时clone 仓库、装 openrig、跑openrig up五分钟就能把 AI 编码环境搭好不用再对着文档一步步折腾。