1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“装配好的成套设备”或者“把零散部件搭成一套能跑的系统”比如矿机里的 mining rig、音频工作站的 rig、测试台上的 test rig。所以openrig大概率不是一个单点工具而是一套开源的、可组装的工程骨架——把模型、命令行工具、配置文件和本地环境拼成一条能稳定运行的链路。结合热搜词里高频出现的Claude Code、Codex、YAML、npm我基本能判断出这个项目的真实定位它面向的是本地 AI 编码代理coding agent的编排与配置。也就是说你手里可能同时装着 Claude Code、Codex CLI 这类命令行代理工具它们各自有各自的配置文件、各自的模型接入方式、各自的启动参数时间一长就变成一团乱麻。openrig想做的就是用一个统一的 YAML 描述文件把这些工具、模型端点、运行参数“装配”到一起让你换模型、换工具、换项目时不用再翻文档改一堆散落的配置。为什么我这么判断因为热搜词里有一组非常典型的组合claude code 调用lmstudio的本地模型、codex接入deepseek、vscode配置claude code、ubuntu配置claude code。这些搜索行为的共同点是——用户不满足于官方默认的云端模型想把代理工具接到自己的本地模型或第三方模型上。而一旦涉及“接入自定义端点”配置文件就成了绕不开的坎。openrig的价值恰恰在这里它把“工具 模型 端点 参数”这四件事抽象成一份声明式配置用 YAML 管理用 npm 分发。这篇文章适合谁看三类人。第一类是把 Claude Code 或 Codex 当日常主力、但每次换环境都要重新配一遍的开发者第二类是想把本地模型比如通过 LM Studio 起的服务接进编码代理、但被配置文件格式劝退的人第三类是团队里负责统一开发环境、想让所有成员的代理工具配置保持一致的技术负责人。下面我会从配置结构、工具接入、环境踩坑、验证方法几个角度把openrig这类项目的核心逻辑讲透。2. openrig 的配置骨架YAML 里到底该写什么2.1 为什么是 YAML而不是 JSON 或 TOML先说选型逻辑。这类“装配式”项目几乎都会选 YAML原因很实际它要描述的是层级化的、带注释的、人经常手改的配置。JSON 不支持注释你没法在配置里写“这行是给本地模型用的别删”TOML 虽然支持注释但嵌套结构一深就变得很啰嗦尤其是描述“多个工具、每个工具有多个模型候选”这种树状关系时YAML 的缩进表达最直观。我实测过一个对比同样描述“两个代理工具、每个工具挂两个模型端点”YAML 大概 30 行TOML 要 45 行以上JSON 因为不能写注释实际维护时你得另开一个 README 解释每个字段。所以openrig选 YAML 是合理的热搜里yolov10 yaml文件怎么创建、rstudio的yaml在哪里这类词也说明YAML 已经是配置领域的事实标准学习成本低。但 YAML 有个坑必须提前说它对缩进极其敏感而且 tab 和空格不能混用。我见过太多人从网页复制配置粘贴进去后报mapping values are not allowed in this context排查半天发现是某一行用了 tab。建议在编辑器里把 YAML 文件的 tab 自动转成 2 个空格VS Code 里搜editor.insertSpaces和editor.tabSize就能设。2.2 一份可落地的 openrig 配置结构基于这类项目的常见设计我推演出一份合理的配置骨架。注意以下是基于常见实践的合理补全不是官方文档原文你可以按自己项目的实际字段名调整# openrig.yaml version: 1 # 全局默认所有工具继承 defaults: timeout: 120 retry: 2 log_level: info # 模型端点定义工具通过名字引用 endpoints: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: not-needed model: qwen2.5-coder-7b remote-deepseek: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model: deepseek-coder # 工具装配 tools: claude-code: enabled: true endpoint: local-lmstudio args: - --max-tokens - 8192 codex: enabled: true endpoint: remote-deepseek args: []这份配置的核心思想是端点与工具解耦。endpoints段定义“模型服务在哪、叫什么、用什么 key”tools段定义“哪个工具用哪个端点”。这样你想把 Claude Code 从本地模型切到远程模型只改一行endpoint: remote-deepseek就行不用去翻工具自己的配置文件。api_key那里用了${DEEPSEEK_API_KEY}这种环境变量占位符这是必须的。永远不要把真实密钥写进 YAML 然后提交到 git哪怕仓库是私有的。我踩过一次坑本地测试时图省事把 key 写死在配置里后来同步到团队仓库虽然及时删了但 git 历史里还留着只能整个仓库重建。用环境变量引用配置文件和密钥分离这是底线。2.3 字段设计背后的取舍有人会问为什么不直接让每个工具用自己的原生配置非要套一层 openrig答案是统一入口降低认知负担。Claude Code 有自己的配置位置Codex 有自己的VS Code 插件还有自己的三套配置格式不一样、位置不一样。openrig 相当于一个“总控台”你只维护一份 YAML它负责把配置翻译成各个工具能读的格式。但这里有个现实约束openrig 必须知道每个工具的原生配置长什么样。所以这类项目通常会内置一组“适配器”每个适配器负责把统一的 YAML 转成对应工具的配置。这意味着如果某个工具升级后改了配置格式openrig 的适配器也得跟着更新。选型时要留意项目的更新频率一个半年没更新的适配器很可能已经对不上新版工具了。3. 把 Claude Code 和 Codex 接进 openrig 的实际操作3.1 环境准备npm 这一关先过热搜里npm : 无法加载文件 d:\program files\nodejs\npm.ps1因为在此系统上禁止运行脚本这个报错出现频率极高我几乎每次帮人配环境都会遇到。这不是 npm 坏了是Windows PowerShell 的执行策略默认禁止运行脚本。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedRemoteSigned的意思是本地写的脚本可以跑从网络下载的脚本需要签名。这比直接设成Unrestricted安全也比Restricted实用。改完之后npm -v就能正常输出了。另一个高频问题是npm 国内源。默认源在国内访问经常超时装个包等半天。切换镜像源npm config set registry https://registry.npmmirror.com npm config get registry # 验证是否生效如果哪天要发布自己的包热搜里有发布npm包记得临时切回官方源https://registry.npmjs.org因为镜像源通常只读不写。我一般用nrm这个工具管理多个源nrm use taobao、nrm use npm一键切换比手动改配置省事。3.2 安装与初始化 openrig假设 openrig 通过 npm 分发这是最符合热搜词npm安装的方式安装流程大致是# 全局安装 npm install -g openrig # 验证 openrig --version # 在项目目录初始化配置 openrig initopenrig init会在当前目录生成一份openrig.yaml模板。这里有个经验不要一上来就在全局配置里折腾先在单个项目目录里跑通。因为全局配置一旦写错可能影响你所有项目的代理工具启动排查起来很痛苦。等项目级配置验证稳定了再考虑抽成全局模板。初始化后你需要确认两件事一是endpoints里的本地模型服务确实起来了比如 LM Studio 的 server 模式是否在监听 1234 端口二是tools里启用的工具确实已经装好。openrig 本身通常不负责安装 Claude Code 或 Codex它只负责“装配”工具本体还得你自己装。3.3 Claude Code 的接入要点Claude Code 接入自定义端点时最容易卡在端点格式上。它期望的是 OpenAI 兼容的/v1/chat/completions接口而 LM Studio 默认起的服务正好兼容这个格式所以base_url填http://127.0.0.1:1234/v1就行。但如果你用的是别的本地推理框架接口路径可能不一样得先确认它暴露的是不是 OpenAI 兼容接口。热搜里claude code 调用lmstudio的本地模型这个需求实操步骤是先在 LM Studio 里加载一个编码能力强的模型比如 Qwen2.5-Coder 系列启动 Local Server记下端口然后在 openrig 的endpoints里定义这个端点最后把claude-code工具的endpoint指向它。启动 Claude Code 时openrig 会把端点信息注入到工具能读到的位置。注意本地模型的能力和云端模型差距明显尤其是长上下文和复杂工具调用。用本地模型跑 Claude Code 时如果发现它频繁“忘记”前面的对话或者工具调用格式出错大概率是模型本身能力不够不是配置问题。建议先用一个中等复杂度的任务测试别一上来就丢个大重构给它。3.4 Codex 的接入与端点切换Codex CLI 的接入逻辑类似但它对端点的要求可能更严格。热搜里codex接入deepseek说明很多人想用 DeepSeek 的 API 替代默认模型。DeepSeek 提供 OpenAI 兼容接口所以配置方式和本地模型一致只是base_url换成https://api.deepseek.com/v1api_key换成你的真实 key通过环境变量注入。这里有个实测经验不同工具对model字段的命名要求不一样。有的工具要求填模型 ID如deepseek-coder有的要求填显示名。如果启动后报“模型不存在”先检查这个字段。另外codex无法加载组织设置这类报错通常和账号权限或组织策略有关不是 openrig 能解决的得去工具本身的账号设置里看。切换端点时我建议用 openrig 的“配置档”功能如果项目支持。比如定义profiles.local和profiles.remote两套用openrig use local一键切换。这样比手动改 YAML 再重启工具高效得多也避免了改错字段。4. 那些让人抓狂的报错从现象到根因的排查链路4.1cc switch local proxy failed while handling codex endpoint /responses这个报错信息量很大我拆开看cc switch可能是某个切换脚本或命令local proxy说明中间有一层本地代理handling codex endpoint /responses说明代理在处理 Codex 的/responses路径时失败了。根因通常有三种第一种代理没起来或者端口被占。本地代理一般监听某个固定端口如果这个端口被别的程序占了代理起不来请求自然失败。排查方法netstat -ano | findstr :端口号Windows或lsof -i :端口号macOS/Linux看端口有没有被占用。第二种端点路径不匹配。Codex 可能请求的是/responses但你的本地模型服务只提供/v1/chat/completions路径对不上就 404。这时候要么在代理层做路径重写要么换一个兼容/responses的服务。第三种代理配置里的端点地址写错了。比如把http://127.0.0.1:1234写成了http://localhost:1234在某些环境下 localhost 解析到 IPv6 而服务只监听 IPv4就会连接失败。统一用127.0.0.1而不是localhost这是我踩过坑之后的固定习惯。4.2your organization has disabled claude subscription access for claude code这个报错和 openrig 无关是账号层面的策略限制。意思是你的组织管理员关闭了 Claude Code 的订阅访问权限。遇到这个配置怎么改都没用只能找管理员开通或者换一个个人账号。别在这个报错上浪费时间调配置先确认账号权限这是排查顺序的问题。4.3 YAML 解析失败的典型表现YAML 报错往往很隐晦。常见的有报错信息根因解决mapping values are not allowed here冒号后没空格或用了 tab冒号后加空格tab 转空格found character \t that cannot start any token缩进用了 tab全部改成空格could not find expected :某行少了冒号检查该行结构duplicate key同一个 key 写了两遍删掉重复项我处理 YAML 报错的标准流程是先把文件丢进在线 YAML 校验器搜yaml validator就有它会直接告诉你第几行第几列出问题。比肉眼一行行看快十倍。校验通过后再喂给 openrig能排除掉大部分低级错误。4.4 环境变量没生效导致的“密钥为空”用${VAR}占位符时如果环境变量没设openrig 解析出来就是空字符串然后请求带着空 key 发出去服务端返回 401。这种报错信息通常不会直接说“你的环境变量没设”而是说“认证失败”。排查方法在启动 openrig 之前先echo $DEEPSEEK_API_KEYLinux/macOS或echo %DEEPSEEK_API_KEY%Windows CMD确认变量有值。Windows 下设置环境变量后必须重开终端才生效这点很多人会忽略。5. 让 openrig 真正好用的几个进阶思路5.1 用配置档管理多套环境开发者的机器上通常有多个场景公司项目用公司内网端点个人项目用本地模型临时测试用第三方 API。如果每次切换都手改 YAML迟早改乱。合理的做法是在 openrig 里支持配置档profiles: work: endpoint: company-internal tool: claude-code personal: endpoint: local-lmstudio tool: claude-code test: endpoint: remote-deepseek tool: codex启动时openrig run --profile work就能加载对应配置。这样不同环境的配置互不干扰也不会出现“把公司 key 提交到个人仓库”这种事故。5.2 把 openrig 配置纳入版本控制openrig.yaml应该提交到 git但密钥绝对不能。做法是配置文件里只写${VAR}占位符真实密钥放在.env文件里.env加入.gitignore。团队协作时新成员 clone 下来后复制一份.env.example改成.env填上自己的 key 就能跑。这套模式在各类项目里已经非常成熟openrig 场景同样适用。5.3 和 VS Code 的配合热搜里vscode配置claude code、claude code for vs code说明很多人是在 VS Code 里用这些工具的。openrig 的配置可以和 VS Code 的工作区设置联动在.vscode/settings.json里指定 openrig 配置路径或者用任务task在打开工作区时自动执行openrig apply。这样团队成员打开项目代理工具的配置就自动对齐了不用每个人手动配一遍。5.4 日志与调试openrig 这类“中间层”工具出问题时最难的是定位是哪一层挂了。建议在配置里把log_level设成debug让它把每次请求的端点、路径、响应码都打出来。看到日志你就知道是 openrig 没把配置传对还是工具本身请求格式有问题还是模型服务返回了错误。没有日志的中间层就是黑盒调试成本极高。6. 我在实际装配过程中总结的几条硬经验第一条先跑通最小链路再叠加复杂度。不要一上来就配三个工具、四个端点、两套配置档。先用一个工具接一个本地端点确认能正常对话再加第二个工具。每加一层都验证一次出问题能立刻定位到刚加的那层。第二条端口和地址统一用127.0.0.1。前面说过 localhost 的解析问题这个坑我在不同项目里踩过至少三次每次都是排查半天才想起来。固定用127.0.0.1能省掉这类玄学问题。第三条工具的版本和 openrig 的适配器版本要对齐。Claude Code 和 Codex 都在快速迭代配置格式可能变。升级工具后如果 openrig 突然不工作第一反应应该是查 openrig 有没有对应版本的适配器更新而不是怀疑自己的配置写错了。第四条本地模型的能力边界要心里有数。用本地模型接编码代理适合的是补全、简单重构、写测试这类任务。复杂的跨文件重构、需要长上下文推理的任务本地小模型力不从心。把合适的任务交给合适的模型比强行让本地模型干所有活更实际。第五条配置文件的注释要写给自己看。YAML 支持注释别浪费。每个端点为什么这么配、每个参数为什么是这个值写一行注释。三个月后你回头看会感谢当时的自己。我见过太多“当时配好了但不知道为什么这么配”的配置改的时候完全不敢动。这套东西说到底核心价值不在于 openrig 这个工具本身有多强而在于它把“工具、模型、端点、参数”这四件容易散落的东西收拢到一份可读、可版本控制、可切换的配置里。你把这套逻辑吃透哪怕以后不用 openrig换成别的编排工具思路是一样的。