openrig 本地 AI 编码代理环境搭建与 YAML 配置实战指南

1. openrig 到底想解决什么问题第一次看到openrig这个名字我下意识把它拆成了 “open” 和 “rig” 两部分。rig 在工程语境里通常指“装配、搭建、成套设备”放到软件领域它更像是一套“把零散部件组装成可用系统”的脚手架。结合热搜词里高频出现的claude code、codex、yaml、node.js我基本能判断出openrig 面向的是本地 AI 编码代理的运行环境搭建与配置管理这一类需求。说白了很多人现在手里都有不止一个 AI 编码工具有人用 Claude Code 做终端里的结对编程有人用 Codex 跑代码补全和任务代理还有人想把本地模型接进来省钱。但真到动手的时候问题全来了——Node.js 版本不对、YAML 配置文件不知道放哪、工具之间互相抢端口、组织策略把订阅权限禁了、模型名写错直接报 unsupported。openrig 要做的就是把这些“装完就报错”的碎片体验收敛成一套可复现的装配流程。这篇文章适合三类人看第一类是完全没接触过 AI 编码代理、想从零搭一套环境的新手第二类是已经装了 Claude Code 或 Codex但被 YAML 配置和 Node.js 版本折腾得够呛的开发者第三类是想把多个代理工具统一管理、避免重复踩坑的进阶用户。我会围绕 openrig 这个核心把环境准备、配置结构、多工具协同、排错链路讲透所有步骤都尽量给到可直接抄作业的程度。需要先说明一点openrig 本身在公开资料里并没有一个官方定义的标准文档所以下面涉及的具体目录结构、字段命名是基于“一个合格的本地代理装配工具最可能采用的设计”做的合理推演。你在实际使用时以自己拿到的版本为准但底层的原理和排错思路是通用的。2. 装 openrig 之前先把 Node.js 这条地基打牢2.1 为什么 Node.js 版本是第一个拦路虎热搜词里有一条特别扎眼error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错我太熟了几乎每个用 nvm 或 fnm 管理 Node 版本的人都遇到过。它的本质是你指定的版本号在镜像源里根本不存在要么是版本号写错了要么是这个版本还没正式发布要么是你的镜像源同步滞后。openrig 这类工具通常依赖 Node.js 运行时来跑 CLI而不同版本的 Node 对 ESM、顶层 await、fetch API 的支持差异很大。Claude Code 和 Codex 的 CLI 一般都要求 Node 18 以上部分新特性甚至要求 Node 20 LTS 或更高。所以第一步不是急着装 openrig而是把 Node 版本管理干净。我的建议是永远用 LTS 版本不要追最新的奇数版本。LTS 意味着长期支持依赖生态兼容性最好。截至我写这篇内容时Node 20 LTS 和 Node 22 LTS 是最稳的两个选择。2.2 用版本管理器而不是官网安装包很多人图省事直接去 Node.js 官网下载安装包双击。这样做的问题是全局只有一个版本等你哪天需要切到旧版本跑老项目就得卸载重装非常痛苦。正确做法是用版本管理器。在 macOS 和 Linux 上我推荐fnmFast Node Manager它比 nvm 启动快很多Windows 上可以用nvm-windows或者直接在 WSL 里用 fnm。安装命令大致如下# macOS 用 Homebrew 装 fnm brew install fnm # 在 shell 配置里启用 fnm以 zsh 为例 eval $(fnm env --use-on-cd)装完之后安装并切换到 LTSfnm install 22 fnm use 22 node -v # 应该输出 v22.x.x注意如果你在 Windows 原生环境用 nvm-windows安装路径里千万不要带空格和中文否则后面 CLI 调用 Node 时会因为路径解析失败而报奇怪的错。这是我踩过的真实坑。2.3 镜像源与网络环境的取舍国内环境下npm 官方源拉包经常超时。这时候可以切到国内镜像源加速npm config set registry https://registry.npmmirror.com但要注意有些 AI 编码工具的 CLI 在安装时会去拉 GitHub Release 里的二进制文件这部分不走 npm 源镜像加速帮不上忙。如果卡在这一步可以配置工具的下载代理参数或者手动下载二进制放到指定目录。openrig 如果提供了离线安装模式优先用离线包能省掉大量网络不确定性。2.4 验证 Node 环境是否真的可用装完别急着往下走先做三项验证node -v看版本、npm -v看包管理器、npx --version看能否执行临时包。三项都正常再确认一下全局 bin 目录在 PATH 里npm config get prefix # 输出的路径下的 bin 目录应该在 PATH 中这一步很多人跳过结果后面装完 CLI 提示command not found又回头折腾半天。提前验证能省半小时。3. openrig 的 YAML 配置结构、字段与放置位置3.1 YAML 为什么成了这类工具的标配热搜里yolov10 yaml文件怎么创建、rstudio的yaml在哪里、yaml安装这些词混在一起说明很多人对 YAML 的认知还停留在“听说过但不会写”。YAML 之所以被 openrig 这类工具选为配置格式核心原因是可读性强、支持嵌套、天然适合描述层级化的配置。相比 JSON它没有那么多引号和括号相比 TOML它表达复杂嵌套结构更自然。但 YAML 也是出了名的“缩进敏感”。一个空格之差整个配置就可能解析失败。我见过太多人因为 tab 和空格混用导致工具启动时报yaml: found character that cannot start any token。所以第一条铁律YAML 里永远只用空格缩进绝不用 Tab。3.2 openrig 配置文件的典型结构推演基于这类工具的通用设计openrig 的配置文件大概率长这样一个主配置文件负责全局设置若干个子配置分别描述不同的代理端点、模型映射和工具行为。下面是我推演的一个结构示例# openrig.yaml version: 1 runtime: node: 22 packageManager: npm endpoints: - name: local-codex type: codex baseUrl: http://127.0.0.1:8080 model: gpt-5.6-sol timeout: 30000 - name: local-claude type: claude-code baseUrl: http://127.0.0.1:8081 model: claude-sonnet timeout: 30000 logging: level: info file: ./logs/openrig.log这里每个字段都有它的意义。version用于配置格式的向后兼容runtime锁定运行时版本避免换机器后行为不一致endpoints是核心每个端点描述一个 AI 服务的接入信息logging控制日志排错时把 level 调到 debug 能看到完整请求链路。3.3 配置文件该放在哪三个候选位置“rstudio 的 yaml 在哪里”这类搜索背后是大家对配置文件位置的普遍困惑。openrig 的配置一般有三个候选位置优先级从高到低优先级位置适用场景1当前工作目录下的openrig.yaml项目级配置随项目走2用户主目录~/.config/openrig/config.yaml全局默认配置3环境变量OPENRIG_CONFIG指定的路径CI/CD 或特殊部署工具启动时会按这个顺序查找找到第一个就用。这意味着你可以在项目里放一份覆盖全局的配置非常灵活。但也要注意如果你在项目目录里放了一份配置却忘了它覆盖了全局配置就会出现“明明改了全局配置却不生效”的迷惑现象。排查时先确认当前生效的是哪一份。3.4 模型名写错引发的连锁反应热搜里有一条报错特别典型{detail:the gpt-5.6-sol model is not supported when using codex with a...}。这类错误的根源是模型标识符和服务端实际支持的模型列表不匹配。AI 编码工具在启动时会向端点发一个探测请求如果返回的模型列表里没有你配置的名字就会直接拒绝。解决办法有两个一是查端点实际支持的模型名很多本地推理服务会在/v1/models接口暴露可用列表二是用通配或别名机制让 openrig 在转发时做一次映射。我个人的习惯是配置里永远写服务端真实存在的模型名别名映射放在 openrig 层做这样出问题时能快速定位是配置层还是服务层的问题。4. 多工具协同Claude Code、Codex 与本地模型的接入逻辑4.1 为什么要把它们放在一起管单独用 Claude Code 或单独用 Codex其实不需要 openrig。真正需要 openrig 的场景是你同时用多个工具且它们共享一部分配置。比如你希望 Claude Code 和 Codex 都走同一个本地模型端点或者你希望两个工具的日志统一收集、端口统一分配。这时候如果没有一个中间层你就得在每个工具里各配一遍改一次配置要改好几个地方极易出错。openrig 的价值就在于做这个“中间层”工具只管调用 openrig 暴露的统一接口openrig 负责把请求路由到正确的后端。这有点像微服务里的 API 网关只不过管的是 AI 编码代理。4.2 Claude Code 接入本地模型的关键点热搜里claude code 调用lmstudio的本地模型是个高频需求。Claude Code 默认走官方服务要让它走本地模型核心是改它的端点配置。通常通过环境变量或配置文件指定baseUrl和apiKey。本地模型服务比如 LM Studio一般暴露一个兼容 OpenAI 协议的接口Claude Code 需要的是 Anthropic 协议两者协议不同中间就需要一个转换层。openrig 如果内置了协议转换那配置就简单了在 endpoints 里声明一个type: claude-code的端点指向本地服务openrig 自动做协议适配。如果没有内置你就得自己跑一个转换代理。这里的关键经验是协议转换层一定要单独验证先用 curl 直接打本地服务的接口确认它能返回正常响应再让 openrig 去接。否则出了问题你分不清是转换层坏了还是 openrig 配错了。4.3 Codex 接入第三方模型的注意事项codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型这些搜索说明大家普遍想把 Codex 接到非官方模型上。Codex 的 CLI 通常支持通过配置指定自定义端点。接入第三方模型时最容易出问题的是认证方式和请求格式。认证方面有些第三方服务用 Bearer Token有些用自定义 Header配置时要看清楚。请求格式方面Codex 可能发送一些官方特有的字段第三方模型不认就会报 400。这时候要么在 openrig 层做字段裁剪要么换一个兼容性更好的模型服务。提示接入第三方模型前先用最简的 curl 请求验证端点连通性和认证确认无误再写进 openrig 配置。这一步能过滤掉八成的问题。4.4 端口冲突与进程管理多个工具同时跑端口冲突是家常便饭。openrig 如果负责分配端口最好在配置里显式指定每个端点的端口而不是让它随机分配。显式指定后你就能用lsof -i :端口号快速定位是谁占用了端口。进程管理方面我建议用 openrig 统一拉起和关闭所有子进程而不是手动一个个开。手动开的问题是关的时候容易漏导致端口被僵尸进程占着下次启动就报address already in use。统一管理能避免这个问题。5. 报错排查从 cc switch 失败到组织策略禁用5.1cc switch local proxy failed的完整排查链路热搜里有一条很具体的报错cc switch local proxy failed while handling codex endpoint /responses。这个报错信息量很大我们逐层拆解。第一层cc switch是切换工具它负责在不同配置之间切换。local proxy failed说明本地代理启动失败。while handling codex endpoint /responses说明失败发生在处理 Codex 的/responses端点时。排查顺序应该是这样的确认代理进程是否真的起来了。用ps aux | grep openrig或类似命令看进程在不在。不在的话看启动日志。确认端口是否被占用。lsof -i :代理端口如果被占用换端口或杀掉占用进程。确认/responses端点是否可达。用 curl 直接打这个端点看返回什么。如果是 404说明路由配置错了如果是 500说明后端服务有问题。确认后端模型服务是否正常。代理只是转发真正干活的是后端。后端挂了代理自然失败。看代理日志的详细堆栈。把日志级别调到 debug通常能看到具体的失败原因。这个链路我走过很多次绝大多数问题出在第 2 步和第 4 步。端口冲突和后端服务没起来占了故障的七成以上。5.2 组织策略禁用订阅的应对思路your organization has disabled claude subscription access for claude code这条报错本质是账号层面的策略限制不是技术配置问题。遇到这种情况技术手段能做的很有限因为限制在服务端。可行的方向是确认自己用的是个人账号还是组织账号如果是组织账号且策略被锁需要联系组织管理员如果是个人账号出现这个提示检查一下订阅状态是否正常。我的经验是这类账号策略问题不要试图用技术绕过浪费时间且不稳定。正确的做法是理清账号归属和订阅关系从源头解决。5.3 模型不支持类报错的通用处理前面提到的model is not supported是一类通用错误。处理这类错误的通用流程是先查端点支持的模型列表确认你要用的模型在不在列表里。如果不在换一个支持的模型或者升级后端服务。如果在列表里却还报错检查模型名的大小写和拼写很多服务对模型名大小写敏感。最后检查 openrig 的映射配置确认没有把模型名映射错。5.4 常见报错速查表报错关键词大概率原因优先排查动作node.js vXX is not yet released版本号不存在或镜像滞后换 LTS 版本检查镜像源local proxy failed代理进程未起或端口冲突查进程、查端口占用model is not supported模型名不匹配查端点模型列表organization has disabled账号策略限制确认账号归属与订阅yaml cannot start any token缩进用了 Tab全文替换 Tab 为空格address already in use端口被占lsof 定位并清理6. 把 openrig 用顺手的几个实操心得6.1 配置版本化别让环境漂移openrig 的配置文件一定要纳入版本管理。我见过太多人配置改着改着就乱了换台机器重新配一遍结果行为不一致。把openrig.yaml提交到 Git每次改动都有记录出问题能回滚。敏感信息比如 API Key用环境变量注入不要硬编码在配置里。6.2 日志分级排错时才不抓瞎平时把日志级别设成info别一直开debug否则日志文件涨得飞快。真出问题时临时调到debug复现一次拿到完整日志后再调回去。日志文件建议按天切割避免单个文件过大打不开。6.3 先跑通单端点再上多端点新手最容易犯的错是一上来就配一堆端点结果哪个都不通排查起来互相干扰。正确顺序是先配一个端点跑通确认请求能正常返回再加第二个确认两个能共存最后才上复杂的路由规则。增量式配置问题定位成本最低。6.4 环境隔离别让全局配置污染项目如果你同时维护多个项目每个项目对模型和端点的需求可能不同。这时候用项目级配置覆盖全局配置而不是改全局配置。全局配置保持一个稳定的默认值项目配置按需覆盖。这样切换项目时不会互相影响。6.5 定期清理僵尸进程AI 编码代理的进程有时候不会随终端关闭而退出尤其是后台启动的代理。养成习惯每次收工前检查一下有没有残留进程或者用 openrig 的统一关闭命令清理。残留进程占着端口下次启动就报错这种问题最烦人。6.6 备份一份能用的配置当你折腾出一份稳定可用的配置后立刻备份一份命名成openrig.yaml.bak或者提交到一个专门的分支。后面再折腾新功能时万一搞崩了能一键回滚到可用状态。这个习惯帮我省了无数次重配的时间。7. 关于 openrig 后续可以怎么扩展openrig 这类工具的天花板其实很高。往小了说它是个配置管理器往大了说它可以演变成一个本地的 AI 能力调度中心。我目前能想到的几个扩展方向一是加健康检查定期探测每个端点的可用性不可用就自动切换备用端点二是加用量统计记录每个模型被调用了多少次、耗时多少方便做成本分析三是加配置校验在启动前就把 YAML 里的字段错误、模型名错误检查出来而不是等运行时报错。这些扩展不一定都要自己实现但理解它们的存在能帮你在使用 openrig 时更有方向感。工具是死的需求是活的把工具用成自己工作流的一部分才是它真正的价值所在。