1. openrig 到底是什么从一个标题拆出来的真实需求第一次看到 openrig 这个词我脑子里蹦出来的不是某个具体产品而是一类很典型的需求把散落在各处的 AI 编码工具用一个统一的、可配置的、开源的方式装配起来。rig 这个词在英文里有装配、搭台子的意思open 则点明了它的开源属性。合在一起openrig 想干的事情就很清楚了——给 Claude Code、Codex 这类命令行 AI 编码助手搭一个开放的配置骨架让它们能被统一管理、统一切换、统一接入不同的模型后端。为什么会有这种需求因为现在用 AI 写代码的人手里往往不止一个工具。Claude Code 擅长长上下文理解和复杂重构Codex 系列在补全和快速生成上很顺手本地还跑着 LM Studio 或者接入了 DeepSeek、Qwen、GLM 这些模型的第三方 API。工具一多问题就来了每个工具都有自己的配置文件、自己的环境变量、自己的模型映射规则。今天想用 Claude Code 调本地模型明天想让 Codex 走 DeepSeek 的接口后天又想在 VS Code 里同时用两个——如果没有一套统一的装配方案光是改配置就能把人折腾疯。openrig 要解决的就是这个装配问题。它大概率是一个基于 YAML 配置 Node.js 运行时的工具集或者配置框架核心思路是用一份声明式的配置文件描述清楚我要用哪些 AI 编码工具、每个工具走哪个模型端点、各自的参数是什么然后由 openrig 负责把这些配置翻译成各个工具能识别的格式完成注入和启动。这跟当年 Docker Compose 解决多个容器怎么编排是同一个思路——你不需要记住每个容器的启动参数写一份 compose 文件就行。适合谁来参考三类人最需要。第一类是同时使用多个 AI 编码工具的开发者尤其是那些在 Claude Code 和 Codex 之间来回切换的人。第二类是想把本地模型接入云端工具链的玩家比如用 LM Studio 跑本地模型然后让 Claude Code 去调用。第三类是团队里负责工具链统一的技术负责人需要一套可复制、可版本管理的配置方案而不是每个人各自为战。如果你只是偶尔用用一个工具那 openrig 这套东西可能有点重但只要你的工具超过两个或者需要在不同模型后端之间频繁切换这套装配思路就非常值得研究。2. 核心设计思路为什么是 YAML Node.js 这套组合2.1 声明式配置为什么比命令行参数更靠谱openrig 选择 YAML 作为配置载体这个决定背后有很实在的考量。你完全可以用命令行参数来启动 Claude Code 或者 Codex比如指定模型、指定 API 端点、指定超时时间。但命令行参数的问题是它是一次性的、不可追溯的、难以版本管理的。今天你敲了一长串参数启动成功明天想复现同样的环境得翻历史记录或者凭记忆重敲。团队协作时更麻烦你没法把我是怎么配的这件事优雅地交给同事。YAML 的好处在于它是声明式的。你描述的是最终状态应该是什么样而不是一步步怎么操作。一份典型的 openrig 配置大概长这样version: 1 tools: claude-code: enabled: true provider: local endpoint: http://127.0.0.1:1234/v1 model: qwen2.5-coder-32b env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234 ANTHROPIC_API_KEY: local-key codex: enabled: true provider: deepseek endpoint: https://api.deepseek.com/v1 model: deepseek-coder env: OPENAI_BASE_URL: https://api.deepseek.com/v1 OPENAI_API_KEY: ${DEEPSEEK_KEY}这份配置把用哪些工具、每个工具走哪个后端、模型叫什么、环境变量怎么设全部说清楚了。它可以直接提交到 Git 仓库可以 code review可以按环境开发/测试/生产拆成不同的 profile。这就是声明式的价值——配置即文档配置即契约。提示YAML 对缩进极其敏感一律用空格绝对不要用 Tab。我见过太多人因为编辑器自动把 Tab 转成空格或者反过来导致配置解析失败排查半天以为是工具的问题其实是缩进。2.2 Node.js 作为运行时的现实理由为什么是 Node.js 而不是 Python 或者 Go这里有几个很实际的原因。首先Claude Code 和 Codex 这类工具本身就是 Node.js 生态的产物它们的 CLI 是通过 npm 分发的运行时依赖 Node.js。openrig 要做的核心工作是读取配置、生成各工具需要的环境、拉起子进程用 Node.js 来做这件事跟被装配的工具处在同一个运行时里进程管理、环境变量传递、路径解析都最顺。其次Node.js 的跨平台一致性比较好。同一份 openrig 配置和脚本在 macOS、Linux、Windows 上行为基本一致这对需要多人多机协作的场景很重要。第三npm 生态里有大量现成的库可以处理 YAML 解析、进程管理、模板渲染不需要自己造轮子。版本选择上有个坑要提前说。热搜词里出现了 error installing 24.21.0: node.js v24.21.0 is not yet released这说明有人试图安装一个还不存在的版本。Node.js 的版本号是有规律的偶数大版本是 LTS长期支持奇数大版本是 Current尝鲜。生产环境或者日常开发建议用 LTS 版本比如 20.x 或者 22.x。安装方式上Ubuntu 用户不要直接用 apt 装apt 源里的 Node.js 版本往往很旧推荐用 NodeSource 的源或者 nvm 来管理。# 用 nvm 安装并切换到 Node.js 20 LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v # 应该输出 v20.x.x用 nvm 的好处是可以在多个 Node.js 版本之间切换。有些老项目依赖 Node 16新工具要求 Node 20nvm 让你不用卸载重装就能来回切。这一点在同时维护多个 AI 编码工具时特别有用因为不同工具对 Node.js 版本的要求可能不一样。2.3 统一装配层要解决的三类冲突openrig 这类工具真正要处理的是三类配置冲突。第一类是环境变量冲突。Claude Code 读ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYCodex 读OPENAI_BASE_URL和OPENAI_API_KEY如果你在同一个 shell 里同时导出这两组变量它们本身不冲突但一旦你想让两个工具走同一个本地端点就得分别设置容易漏。openrig 的做法是在配置里为每个工具单独声明 env 块启动时按工具注入互不干扰。第二类是模型名称映射冲突。同一个本地模型在 LM Studio 里可能叫qwen2.5-coder-32b在 Claude Code 的语境里需要映射成它认识的模型名在 Codex 里又是另一套命名。openrig 需要在配置层做一层映射把逻辑模型名翻译成各工具认识的模型名。第三类是端点协议冲突。Claude Code 走的是 Anthropic 的 Messages API 格式Codex 走的是 OpenAI 的 Chat Completions 格式。本地模型服务比如 LM Studio通常只提供 OpenAI 兼容接口这时候就需要一个协议转换层。热搜词里提到的 cc switch local proxy failed while handling codex endpoint /responses 就是这类问题的典型表现——代理在处理 Codex 的/responses端点时失败了本质上是协议不匹配或者端点路径没配对。3. 核心细节拆解配置、端点与模型映射的实操要点3.1 YAML 配置文件的结构设计一份能用的 openrig 配置结构上要分几层。最外层是版本和全局设置中间层是工具列表每个工具下面是该工具的具体参数。我建议的结构是这样version: 1 global: log_level: info proxy_port: 8787 profiles: local: description: 全部走本地 LM Studio cloud: description: 走云端 API tools: claude-code: profile: local endpoint: http://127.0.0.1:1234 model_map: default: qwen2.5-coder-32b fast: qwen2.5-coder-7b codex: profile: cloud endpoint: https://api.deepseek.com/v1 model_map: default: deepseek-coder这里引入了profiles的概念是为了解决同一套工具在不同场景下走不同后端的问题。你在本地开发时用 local profile全部指向本机跑的模型到了需要更强能力的时候切到 cloud profile走云端 API。切换只需要改一个 profile 引用不用动每个工具的细节。model_map则是解决模型名映射问题的。工具在调用时通常会说我要 default 模型openrig 根据 model_map 把它翻译成实际的后端模型名。这样上层工具不用关心后端到底叫什么换后端时只改 model_map 就行。注意YAML 里的布尔值true/false不要加引号加了引号就变成字符串了。同理端口号如果写成8787带引号某些解析器会当成字符串处理传给需要数字的地方可能报错。这类细节在配置量大的时候特别容易埋雷。3.2 端点配置与协议适配的关键参数端点配置是 openrig 最容易出问题的地方。核心要搞清楚三件事base URL 要不要带/v1、路径怎么拼、认证头怎么传。以 Claude Code 接本地 LM Studio 为例。LM Studio 默认在http://127.0.0.1:1234提供 OpenAI 兼容接口完整的 chat 端点是http://127.0.0.1:1234/v1/chat/completions。但 Claude Code 期望的是 Anthropic 格式的端点。这时候有两种做法一是让 LM Studio 直接支持 Anthropic 格式部分版本支持二是通过一个转换代理把 Anthropic 请求转成 OpenAI 请求。配置里要明确区分base URL和完整端点。通常工具接受的是 base URL然后自己拼路径。如果你把完整端点填进 base URL 的位置就会出现路径重复比如变成http://127.0.0.1:1234/v1/chat/completions/v1/messages直接 404。热搜词里的 cc switch local proxy failed while handling codex endpoint /responses 很可能就是路径拼接出了问题——代理收到了/responses请求但它的路由表里没有这个路径或者它期望的是/v1/responses。认证方面本地模型通常不校验 API Key但工具可能强制要求这个字段非空。这时候随便填一个占位值就行比如local-key或者sk-local。但要注意有些工具会校验 Key 的格式比如必须以sk-开头那就得按格式填。配置项本地 LM Studio云端 DeepSeek常见错误base URLhttp://127.0.0.1:1234https://api.deepseek.com多写或少写 /v1API Key任意占位值真实 Key本地填了空值导致校验失败模型名qwen2.5-coder-32bdeepseek-coder名字拼错或大小写不符协议OpenAI 兼容OpenAI 兼容Claude Code 需要转换层3.3 模型映射与回退策略模型映射不只是改个名字那么简单还要考虑回退。什么叫回退就是当首选模型不可用时自动切到备用模型。比如你配置了default: qwen2.5-coder-32b但这个模型太大本地显存不够加载失败这时候如果能自动回退到qwen2.5-coder-7b体验会好很多。在 YAML 里可以这样表达model_map: default: primary: qwen2.5-coder-32b fallback: qwen2.5-coder-7b fast: qwen2.5-coder-7bopenrig 在启动工具前可以先探测 primary 模型是否可用比如发一个轻量的健康检查请求不可用就注入 fallback 的模型名。这个探测逻辑要做得轻不能因为探测本身拖慢启动。我一般建议探测超时设 2 秒超过就认为不可用直接回退。另一个映射细节是上下文窗口。不同模型的上下文长度不一样32b 的模型可能支持 128k7b 的只支持 32k。如果工具按 128k 去发请求小模型会直接报错。所以 model_map 里最好把上下文长度也带上让 openrig 能据此调整工具的配置。4. 完整实操流程从零把 openrig 跑起来4.1 环境准备Node.js 与包管理器的正确安装姿势第一步是把 Node.js 装对。前面说了用 nvm这里把完整流程走一遍。Ubuntu 环境下先装 nvm再装 Node.js 20 LTS然后验证。# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 让 nvm 在当前 shell 生效 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装 Node.js 20 LTS nvm install 20 nvm alias default 20 # 验证 node -v npm -v装完之后建议把 npm 的源换成国内镜像不然装包会很慢。但要注意有些企业内网有自己的私有源换之前先确认。npm config set registry https://registry.npmmirror.com包管理器方面npm 够用但如果你经常装全局包pnpm 会更省空间也更快。openrig 本身如果是通过 npm 分发的用哪个包管理器装都行关键是全局 bin 目录要在 PATH 里。提示如果你在 Windows 上nvm 的 Windows 版本叫 nvm-windows用法略有不同安装包直接去 GitHub release 页面下载。装完之后同样用nvm install 20和nvm use 20。Windows 上还要注意某些工具对路径中的空格和中文敏感尽量把项目放在纯英文无空格的路径下。4.2 安装与初始化 openrig假设 openrig 通过 npm 分发安装命令大概是npm install -g openrig openrig initopenrig init会在当前目录生成一份默认的openrig.yaml配置文件以及一个.openrig目录用来存放运行时状态。初始化之后第一件事是检查生成的配置模板把里面的占位符换成你自己的实际值。如果 openrig 不是通过 npm 分发而是需要从源码构建那流程通常是git clone openrig-repo cd openrig npm install npm run build npm link # 把本地构建的版本链接到全局npm link这一步很关键它让你能在任意目录下用openrig命令同时用的是你本地构建的版本方便调试和改代码。初始化完成后用openrig doctor之类的诊断命令检查环境。这类命令通常会检查 Node.js 版本、配置文件语法、端点连通性、各工具是否已安装。如果 doctor 报错按提示逐个解决不要跳过。4.3 配置 Claude Code 走本地模型Claude Code 接本地模型是很多人最关心的场景。核心是设置两个环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。在 openrig 配置里这样写tools: claude-code: enabled: true env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234 ANTHROPIC_API_KEY: local-key ANTHROPIC_MODEL: qwen2.5-coder-32b然后在 LM Studio 里加载好模型启动本地服务确认http://127.0.0.1:1234/v1/models能返回模型列表。这一步是排查问题的基准——如果这个端点都不通后面全是白搭。启动 Claude Code 时openrig 会把这些环境变量注入到子进程里。你可以用openrig run claude-code这样的命令来启动而不是直接敲claude。这样做的意义在于环境变量是 openrig 管理的不会污染你当前的 shell 会话。实测下来Claude Code 接本地模型最大的坑是上下文长度和工具调用能力。本地小模型在工具调用tool use上经常不稳定表现为该调用工具的时候不调用或者调用格式不对。这不是 openrig 的问题是模型能力的问题。解决办法是换更大的模型或者在配置里降低对工具调用的依赖。4.4 配置 Codex 接入第三方 APICodex 接第三方 API 相对直接因为它本身就是 OpenAI 兼容的。以接入 DeepSeek 为例tools: codex: enabled: true env: OPENAI_BASE_URL: https://api.deepseek.com/v1 OPENAI_API_KEY: ${DEEPSEEK_API_KEY} OPENAI_MODEL: deepseek-coder这里用了${DEEPSEEK_API_KEY}这种变量引用语法意思是这个值从环境变量里读不直接写在配置文件里。这样做是为了安全——配置文件可以提交到 Git但 API Key 不能。openrig 在加载配置时会做变量替换把${...}替换成实际的环境变量值。如果环境变量没设置openrig 应该报一个清晰的错误而不是带着空 Key 去请求然后收到 401。这一点在配置校验阶段就要做掉。Codex 接入时常见的报错是 your organization has disabled... 或者 the model is not supported。前者通常是账号权限问题后者是模型名不对。DeepSeek 的模型名要写准确比如deepseek-coder和deepseek-chat是两个不同的模型用途不一样。4.5 在 VS Code 里同时使用多个工具VS Code 里用 Claude Code 和 Codex通常是通过各自的扩展。openrig 在这里的作用是保证扩展读到的环境变量是一致的、正确的。VS Code 扩展读环境变量的方式有两种一种是读系统环境变量一种是读工作区的.env文件。我建议的做法是让 openrig 生成一个.env文件放在工作区根目录VS Code 的扩展配置里指向这个文件。这样配置的源头还是 openrig.yaml.env只是生成物不手动改。openrig export --format dotenv --output .env这个命令把当前 profile 下的所有环境变量导出成.env格式。VS Code 的 Claude Code 扩展和 Codex 扩展如果支持指定 env 文件路径就指向它。如果不支持那就得在 VS Code 的 settings.json 里手动配或者用 openrig 的 VS Code 集成如果有的话。注意VS Code 扩展和终端里跑的 CLI 可能读的是不同的环境。你在终端里export的变量VS Code 扩展不一定能读到尤其是从图形界面启动的 VS Code。这种情况下要么重启 VS Code 让它继承新的环境变量要么用.env文件的方式显式指定。5. 常见问题与排查技巧实录5.1 端点连接类问题速查端点问题是最高频的。下面这张表是我踩坑总结出来的按报错现象倒查原因。报错现象可能原因排查方法Connection refused本地服务没启动curl 一下端点看是否通404 Not Found路径拼接错误检查 base URL 是否多写/少写 /v1401 UnauthorizedAPI Key 缺失或错误检查环境变量是否注入成功400 Bad Request模型名不对或参数不兼容看返回体里的具体错误信息超时端点不可达或模型加载慢先用 curl 测延迟再调超时参数代理处理 /responses 失败协议或路径不匹配确认代理支持该端点路径排查顺序建议从下往上先确认网络通不通curl 端点再确认认证过不过带 Key 请求再确认模型名对不对请求模型列表最后才怀疑工具本身的配置。这个顺序能帮你快速定位问题在哪一层。5.2 配置解析类问题YAML 解析错误往往报得很模糊比如 did not find expected key 或者 mapping values are not allowed here。这类错误九成是缩进问题。我的经验是统一用 2 个空格缩进编辑器里把 Tab 显示出来看到 Tab 就替换成空格。另外YAML 里的冒号后面必须跟一个空格key:value是错的key: value才对。还有一个隐蔽的坑是特殊字符。如果 API Key 或者模型名里包含:、#、这些字符在 YAML 里可能需要加引号。比如model: qwen:32b会被解析成两个键值对必须写成model: qwen:32b。这种问题在配置看起来明明没错但就是解析失败时优先怀疑。5.3 模型调用类问题模型调用失败的表现很多样。最常见的是模型不存在这通常是模型名拼写问题。本地模型的名称大小写敏感Qwen2.5-Coder和qwen2.5-coder可能被当成两个不同的模型。建议直接从模型列表接口复制名称不要手敲。另一个问题是上下文超限。当你给一个只支持 32k 上下文的模型发了一个 100k 的请求服务端会直接拒绝。openrig 如果能在配置里声明每个模型的上下文长度就可以在发送前做截断或者报错提示而不是让请求白白失败。工具调用tool use失败也很常见。本地模型对 tool use 的支持参差不齐有些模型根本不支持有些支持但格式不对。判断方法是看请求日志里有没有 tool 相关的字段以及模型返回里有没有正确格式的 tool call。如果模型不支持那就只能关掉工具调用功能退化成纯对话模式。5.4 进程与环境隔离类问题openrig 管理多个工具时进程隔离很重要。如果两个工具共享同一个环境变量空间一个工具改了变量可能影响另一个。解决办法是每个工具启动时用独立的子进程环境变量在子进程级别注入而不是在父进程里全局 export。在 Node.js 里用child_process.spawn时通过env选项传入环境变量就是子进程级别的const { spawn } require(child_process); const child spawn(claude, [], { env: { ...process.env, ANTHROPIC_BASE_URL: http://127.0.0.1:1234, ANTHROPIC_API_KEY: local-key }, stdio: inherit });这样 Claude Code 拿到的环境变量是独立的不会影响同时运行的其他工具。stdio: inherit让子进程的输入输出直接连到当前终端交互体验跟直接运行一样。提示Windows 上spawn调用.cmd或.bat文件时需要加shell: true否则会报 ENOENT。但加了shell: true之后环境变量里的特殊字符可能被 shell 解释要注意转义。这是跨平台开发的一个经典坑。6. 我个人的一些实操体会用这套东西有一段时间了有几个体会比较深。第一配置文件一定要进版本控制但 Key 一定要用变量引用。我见过有人把 Key 直接写在 YAML 里然后提交到公开仓库结果 Key 被扫走账单爆炸。openrig 的${VAR}语法就是干这个的用起来。第二本地模型和云端模型的能力差距是客观存在的。本地 7b 的模型做代码补全还行做复杂重构就力不从心。所以我的配置里通常保留两套 profile简单的活走本地省钱省延迟复杂的活切云端。openrig 的 profile 机制让这个切换很顺滑。第三端点探测这个功能值得自己加。openrig 如果没内置可以在启动脚本里加一段健康检查端点不通就提前报错而不是等工具跑到一半才失败。这个提前量能省很多排查时间。最后分享一个小技巧把常用的 openrig 命令做成 shell alias比如alias oropenrig、alias orcopenrig run claude-code、alias orxopenrig run codex。每天敲几十遍的命令省下的时间积少成多。配置这东西用着顺手才会坚持用坚持用才能体现出统一管理的价值。