1. 从 openrig 说起一个被名字耽误的本地 AI 编码环境编排工具第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目直到在几个折腾 Claude Code 和 Codex 的群里反复看到有人提到它才意识到这是个跟本地 AI 编码环境搭建强相关的东西。简单说openrig 解决的是一个非常具体的痛点当你同时想用 Claude Code、Codex 这类命令行 AI 编码助手又想让它们接上本地模型或者第三方 API 的时候配置会变得极其零散——每个工具一套配置文件、一套环境变量、一套认证方式换台机器就得重来一遍。openrig 的思路是用一份 YAML 把模型来源、工具入口、运行参数统一编排起来让 Claude Code、Codex 这些工具都能从同一个配置源读取信息。它适合谁如果你只是偶尔用一下网页版对话那确实用不上。但如果你属于下面这几类人openrig 值得花时间研究一是习惯在终端里写代码、想让 AI 助手直接读写本地文件的开发者二是手里有本地模型比如通过 LM Studio 跑起来的模型想把它接到 Claude Code 或 Codex 上省 token 成本的人三是团队里需要统一 AI 编码工具配置、避免每个人环境不一致导致各种诡异报错的工程负责人。这篇文章我会把 openrig 的定位、YAML 配置逻辑、Node.js 环境准备、Claude Code 与 Codex 的接入方式、以及我踩过的那些坑全部拆开讲清楚。需要先说明一点openrig 本身不是一个模型也不是一个 AI 服务它更像是一个接线盒。它不生产能力它只是把模型能力、工具入口和运行环境三者之间的连接关系用声明式配置固定下来。理解这一点后面所有的配置逻辑就顺了。2. openrig 的核心设计思路为什么用 YAML 做统一编排2.1 声明式配置相比命令行参数的天然优势Claude Code 和 Codex 这类工具默认都支持通过命令行参数或者环境变量来指定模型端点、API Key、超时时间这些东西。问题是参数一多就记不住而且不同工具的变量名还不一样。Claude Code 可能用ANTHROPIC_BASE_URLCodex 可能用另一套命名你每次切换都要重新查文档。openrig 选择 YAML 作为配置载体核心原因就是 YAML 天然适合表达层级化的键值对加列表这种结构而且可读性比 JSON 好注释也支持团队协作时谁改了哪一项一目了然。我自己的体会是声明式配置最大的价值不是省事而是可复现。你把 openrig 的 YAML 提交到仓库里新同事 clone 下来装好 Node.js跑一条命令环境就跟他同事一模一样。这比在群里发一段你先 export 这个再 export 那个要靠谱得多。命令行参数是命令式的你执行一次它生效一次YAML 是声明式的你描述的是最终状态应该是什么样工具负责把它变成现实。2.2 openrig 与 Claude Code、Codex 的关系定位这里必须把关系理清楚否则很容易绕晕。openrig 是编排层Claude Code 和 Codex 是执行层模型不管是云端 API 还是本地 LM Studio是能力层。openrig 不替代 Claude Code也不替代 Codex它是在它们之上做统一入口和配置分发。你可以理解为openrig 是那个帮你把电线接好、开关装好的配电箱Claude Code 和 Codex 是两台不同的电器模型是电网。这种分层设计的好处是解耦。哪天你想把 Codex 从接云端模型换成接本地模型只需要改 openrig 配置里对应的那一小段不用去动 Codex 本身的安装。反过来你想加一个新工具进来只要它支持从环境变量或配置文件读取端点信息就能挂到 openrig 下面。这种配置与工具分离的思路跟现在基础设施领域流行的做法是一致的。2.3 一份配置驱动多工具的取舍分析有人会问为什么不干脆每个工具单独配一份文件非要搞个统一编排这里有个真实的取舍。统一编排的代价是你得先理解 openrig 自己的配置 schema学习成本前置收益是长期维护成本大幅下降。如果你只用一个工具、只接一个模型那确实没必要上 openrig直接配环境变量更快。但现实情况往往是你今天用 Claude Code 接云端明天想试试 Codex 接本地模型后天团队要求统一到某个第三方 API配置一变再变。这时候统一编排的价值就出来了。我个人的判断标准是只要你同时维护两个以上的 AI 编码工具或者需要在多台机器之间同步配置openrig 这类编排工具就值得投入。如果只是单机单工具先用最朴素的方式跑通等需求复杂了再迁移也不迟。技术选型最怕的就是为了用而用把简单问题复杂化。3. 环境准备Node.js 安装与版本选择的那些坑3.1 Node.js 到底在 openrig 体系里扮演什么角色很多人搜node.js是干什么的搜到 openrig 相关的内容说明这个疑问很普遍。在 openrig 这套体系里Node.js 是运行时底座。Claude Code、Codex 这些工具以及 openrig 本身大概率都是基于 Node.js 生态构建的 CLI 工具。没有 Node.js这些命令根本跑不起来。你可以把 Node.js 理解成能让 JavaScript 代码在浏览器之外运行的环境而这些 AI 编码助手恰好是用 JavaScript/TypeScript 写的所以必须依赖它。这里有个常见误区有人以为装了 Node.js 就等于装了 npm其实 npm 是随 Node.js 一起分发的包管理器装 Node.js 的时候默认就带上了。但反过来如果你用的是某些精简版安装方式可能会缺 npm导致后续npm install报错。所以安装完第一件事就是验证node -v和npm -v两个命令都能正常输出版本号。3.2 LTS 版本选择与版本未发布报错的根源热搜词里有一条特别典型error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错我见过太多次了根源在于版本号写错了或者用了一个根本不存在的版本。Node.js 的版本号是严格递增的24.21.0 这种版本如果官方还没发布任何安装器都找不到。解决办法很简单去 Node.js 官网下载页面看当前 LTS长期支持版本是多少用那个确切的版本号。我的建议是永远优先选 LTS 版本不要追最新的 Current 版本。LTS 意味着这个版本会获得长时间的维护和安全更新生态里的各种包对它的兼容性也最好。Current 版本虽然新特性多但经常出现某个依赖包还没适配的情况折腾起来得不偿失。截至我写这篇内容的时候Node.js 的 LTS 主线在 20.x 和 22.x 这个区间具体以官网为准。安装方式上Windows 用户直接去 node.js 官网下载 msi 安装包最省事一路下一步就行。Ubuntu 用户我强烈建议用 NodeSource 的源或者 nvm 来装不要用apt install nodejs因为系统源里的版本往往很旧。nvm 的好处是可以在多个 Node.js 版本之间自由切换遇到某个工具只兼容特定版本时特别有用。# Ubuntu 下用 nvm 安装 Node.js LTS 的典型流程 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v npm -v注意上面这条 curl 命令是从 nvm 官方仓库拉取安装脚本执行前建议先打开脚本看一眼内容确认没有异常再运行。这是使用任何远程脚本的好习惯。3.3 安装后的验证清单与常见环境问题装完 Node.js 别急着往下走先做一轮验证。第一node -v和npm -v都要有输出。第二检查 npm 的全局安装路径是否在 PATH 里否则你npm install -g装的东西会找不到。第三如果你在公司网络环境下npm 的默认源可能访问慢可以换成国内镜像源加速但要注意镜像源同步有延迟某些刚发布的包可能拉不到。# 查看 npm 全局路径 npm config get prefix # 临时切换镜像源仅当前会话 npm config set registry https://registry.npmmirror.com # 验证配置 npm config get registry我踩过的一个坑是在 Windows 上用管理员权限装了一次 Node.js后来又用普通用户装了一次结果 PATH 里有两个 node.exe版本还不一样导致命令行里node -v显示的版本和实际生效的版本对不上。排查方法是用where nodeWindows或which nodeLinux/macOS看看到底调用了哪个路径下的可执行文件。这种多版本共存打架的问题在环境准备阶段不解决后面会以各种莫名其妙的形式爆发出来。4. openrig 的 YAML 配置实战从零写一份能跑的配置4.1 YAML 基础语法速通与常见书写错误在写 openrig 配置之前得先把 YAML 的基本规矩搞清楚因为 YAML 对格式极其敏感一个缩进错误就能让整个文件解析失败。YAML 用缩进表示层级绝对不能用 Tab 缩进只能用空格这是新手最容易犯的错。键值对用冒号加空格分隔列表项用短横线加空格开头。字符串一般不用引号但如果值里包含特殊字符比如冒号、井号就得用引号包起来。# 一个最小化的 YAML 结构示例 name: openrig-demo version: 1 models: - name: local-lmstudio endpoint: http://127.0.0.1:1234/v1 api_key: not-needed - name: cloud-api endpoint: https://api.example.com/v1 api_key: sk-xxxx tools: claude_code: enabled: true model: local-lmstudio codex: enabled: true model: cloud-api上面这段结构里models和tools是两个顶层键各自下面挂着列表或嵌套的键值对。注意- name:这种写法短横线后面跟一个空格然后才是键名这个空格不能省。我见过有人写成-name:结果 YAML 解析器把它当成一个普通的键整个结构就乱了。4.2 模型端点、密钥与工具入口的配置映射openrig 配置的核心就是把模型从哪来和工具用哪个模型这两件事对应起来。模型端点这块如果你接的是本地 LM Studio端点通常是http://127.0.0.1:1234/v1这种形式密钥随便填一个占位符就行因为本地服务一般不校验。如果你接的是第三方 API端点、密钥、模型名这三样必须跟服务商给的完全一致错一个字符都会导致 401 或 404。工具入口这块Claude Code 和 Codex 各自需要读取哪些环境变量openrig 会帮你映射过去。这里的关键是理解映射这个词你在 YAML 里写的是逻辑名称比如local-lmstudioopenrig 负责把它翻译成 Claude Code 认识的ANTHROPIC_BASE_URL和 Codex 认识的对应变量。所以你在 YAML 里改端点两个工具都会跟着变不用分别去改。提示配置里的 API Key 千万不要明文提交到公开仓库。正确做法是用环境变量引用比如api_key: ${MY_API_KEY}然后在本地 shell 里 export 这个变量。openrig 这类工具通常都支持这种变量插值语法。4.3 一份可直接抄作业的 openrig 配置模板下面这份模板是我自己用下来比较稳的结构你可以直接拿去改。它同时定义了本地模型和云端模型两个来源Claude Code 走本地Codex 走云端方便对比测试。version: 1 defaults: timeout: 120 retry: 2 models: local: endpoint: http://127.0.0.1:1234/v1 api_key: local-placeholder model_name: local-model cloud: endpoint: ${CLOUD_API_BASE} api_key: ${CLOUD_API_KEY} model_name: cloud-model-name tools: claude_code: model_ref: local extra_env: ANTHROPIC_BASE_URL: ${models.local.endpoint} ANTHROPIC_API_KEY: ${models.local.api_key} codex: model_ref: cloud extra_env: OPENAI_BASE_URL: ${models.cloud.endpoint} OPENAI_API_KEY: ${models.cloud.api_key}这份配置里我用了model_ref来引用上面定义的模型这样改模型只需要改一处。extra_env是给每个工具单独注入的环境变量因为不同工具的变量名确实不一样。defaults里的超时和重试是全局兜底避免某个请求卡死。5. Claude Code 与 Codex 的接入细节从安装到跑通5.1 Claude Code 安装与 VS Code 集成要点Claude Code 的安装官方推荐的方式是通过 npm 全局安装。装完之后你可以在终端里直接敲claude启动。如果你习惯在 VS Code 里工作可以装对应的扩展让 Claude Code 直接在编辑器里读写文件。VS Code 配置 Claude Code 的关键是确保扩展能找到你终端里的claude命令有时候 PATH 不一致会导致扩展启动失败这时候在扩展设置里手动指定可执行文件路径就行。Ubuntu 下配置 Claude Code 和 Windows 下略有不同主要是路径和权限的问题。Ubuntu 下如果用 nvm 装的 Node.js全局安装的包在~/.nvm/versions/node/vXX/bin下面这个路径要确保在 PATH 里。Windows 下则是%APPDATA%\npm这个目录。搞不清楚的时候npm config get prefix会告诉你全局包装在哪。热搜里有个报错值得单独说your organization has disabled claude subscription access for claude code。这个不是技术问题是账号权限问题说明你所在的组织在管理后台关掉了 Claude Code 的订阅访问。遇到这个只能找管理员开权限自己折腾配置是没用的。区分配置问题和权限问题很重要能省下大量无效排查时间。5.2 Codex 安装教程与登录流程拆解Codex 的安装同样走 npm 全局安装的路子装完用codex命令启动。首次使用需要登录登录方式通常是浏览器授权或者填 API Key。Codex 登录这块热搜里有个codex无法加载组织设置的报错这个多半是网络请求超时或者账号状态异常导致的。排查顺序是先确认网络能正常访问服务端点再确认账号本身没问题最后看是不是配置文件里有残留的旧设置干扰。Codex 接入 DeepSeek 这类第三方模型核心是改端点。Codex 默认连的是官方端点你要在 openrig 配置或者环境变量里把端点指向 DeepSeek 的兼容接口。这里要注意不是所有第三方接口都完全兼容 OpenAI 的协议格式有些字段名或者返回结构有细微差异会导致 Codex 解析失败。遇到这种情况先看 Codex 的日志输出通常会告诉你哪个字段不符合预期。5.3 用 openrig 统一管理两个工具的启动参数把 Claude Code 和 Codex 都挂到 openrig 下面之后启动方式就统一了。你不再需要记两套环境变量而是通过 openrig 的命令来拉起对应工具它会自动注入正确的配置。这种统一入口的价值在团队协作时特别明显新人只需要装好 Node.js、clone 配置仓库、跑一条启动命令就能得到和老手一样的环境。我实测下来openrig 这种编排方式对频繁切换模型来源的场景帮助最大。比如白天用云端模型保证质量晚上用本地模型省钱切换只需要改 YAML 里的一行model_ref然后重启工具。如果不用编排你得手动 export 一堆变量还容易漏掉某个导致行为不一致。6. 常见报错与排查技巧实录6.1 配置类报错的定位思路codex is ignoring 1 unrecognized configuration setting. check for typos or d...这条报错的意思是 Codex 读到了一个它不认识的配置项直接忽略了。这通常是因为你抄的配置模板版本和当前 Codex 版本不匹配某个字段在新版里改名了或者被移除了。解决办法是去查当前版本的官方配置文档对照着删掉或改名。不要觉得忽略就忽略吧有时候被忽略的恰恰是关键配置会导致行为跟预期完全不符。排查配置类问题我的习惯是先把配置精简到最小可用集跑通之后再一项一项加回去。这样一旦出问题就能立刻定位到是哪一项引入的。这跟调试代码时注释掉一半逻辑的思路是一样的二分法定位效率最高。6.2 网络与端点类报错的排查顺序cc switch local proxy failed while handling codex endpoint /responses这类报错关键词是local proxy failed说明本地代理层在处理 Codex 的/responses端点时出错了。排查顺序应该是第一确认本地模型服务比如 LM Studio确实在运行端口对得上第二用 curl 直接打一下那个端点看返回什么第三检查 openrig 配置里的端点路径有没有多写或少写/v1之类的后缀。# 直接测试本地模型端点是否可用 curl http://127.0.0.1:1234/v1/models # 测试对话端点 curl -X POST http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:local-model,messages:[{role:user,content:hi}]}如果 curl 能通但工具报错那问题就在工具的配置映射上不在模型服务本身。这个区分能帮你快速缩小排查范围。6.3 常见问题速查表报错关键词可能原因排查方向node.js vXX not yet released版本号写错或不存在去官网核对确切 LTS 版本号organization has disabled access组织权限被关闭联系管理员非配置问题unrecognized configuration setting配置项与版本不匹配对照当前版本文档核对字段名local proxy failed本地端点不通或路径错误curl 直测端点检查路径后缀无法加载组织设置网络超时或账号异常先测网络再查账号状态这张表是我自己遇到问题后整理的基本覆盖了新手最常撞的几类墙。遇到没见过的报错第一反应应该是看完整日志而不是只看最后一行。很多关键信息藏在日志中间被最后那行总结性报错盖住了。7. 我踩过的坑与几条实在的经验说几个文档里不会写、但实际会遇到的坑。第一个是 YAML 的缩进混用问题。有些编辑器默认用 Tab你看着缩进对齐了实际上一个是 Tab 一个是空格YAML 解析器直接报错。解决办法是在编辑器里开启显示空白字符一眼就能看出 Tab 和空格的区别。第二个是环境变量的作用域问题。你在当前终端 export 的变量换个终端窗口就没了如果 openrig 是在另一个进程里读这些变量就会读不到。稳妥的做法是把变量写进 shell 的配置文件比如.bashrc或.zshrc或者直接用 openrig 支持的.env文件加载机制。第三个坑是关于本地模型的并发能力。本地 LM Studio 跑的模型并发请求数通常很低如果你同时让 Claude Code 和 Codex 都打同一个本地端点很容易出现排队甚至超时。我的做法是给两个工具分配不同的模型来源或者错开使用时间。第四个坑是 API Key 的格式。有些第三方服务要求 Key 带特定前缀有些要求放在 Header 里而不是 query 参数里这些细节在 openrig 配置里都要对应写清楚否则就是 401。最后分享一个提高排查效率的小技巧在 openrig 配置里把日志级别调到 debug这样每次请求的端点、参数、返回状态都会打出来。虽然日志会变多但出问题时能一眼看到是哪一步断的。等环境稳定了再调回正常级别避免日志刷屏。这套东西折腾下来你会发现真正难的不是某个工具的安装而是把多个工具、多个模型来源、多台机器之间的配置关系理顺。openrig 这类编排工具的价值恰恰就在于把这层关系用一份可读、可版本控制的 YAML 固定下来让环境问题从玄学变成可复现、可排查的工程问题。