openrig 装配指南：Claude Code 与 Codex 本地模型接入实战

1. 从openrig这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是open加rig的组合。rig 在工程语境里通常指装配、搭建一套可运行的环境比如测试台架、实验装置。所以 openrig 从命名上就带着一股把某套东西开放地组装起来的味道。结合热搜词里高频出现的 Claude Code、Codex、YAML、npm 这些关键词我基本可以判断这是一个围绕 AI 编程助手Claude Code / Codex CLI做本地化配置、环境装配、模型接入的开源工具或配置方案集合。为什么我这么判断因为热搜词里几乎全是安装配置接入本地模型镜像源这类词。claude code 调用lmstudio的本地模型、codex接入deepseek、vscode配置claude code、ubuntu配置claude code——这些搜索行为的背后是一群想把 AI 编程助手真正跑在自己机器上、接自己想要的模型、并且能稳定用起来的人。而 openrig 很可能就是为这群人准备的一套装配说明书或者脚手架。我先把话说在前面这篇文章不是官方文档的翻译也不是简单的命令罗列。我会按照一个真实从业者的思路把为什么需要 openrig 这类东西它背后的核心技术点是什么实际装配时会踩哪些坑怎么验证装好了这几个问题讲透。如果你正好在折腾 Claude Code 或 Codex 的本地环境或者你只是好奇这类工具到底怎么落地这篇内容应该能帮你省下不少翻论坛的时间。需要说明的是由于输入里项目正文和关键词都是空的下面的技术细节是我基于热搜词反映出的真实需求场景结合这类工具常见的实现方式做的合理推演和补充。凡是推演的部分我都会明确标注出来避免误导。2. openrig 背后的核心领域AI 编程助手的本地装配层2.1 为什么装配这件事本身值得单独做一个项目很多人会问Claude Code、Codex 这些工具不是官方给了安装命令吗为什么还要搞一个 openrig这个问题的答案藏在热搜词里那句cc switch local proxy failed while handling codex endpoint /responses里。这句话翻译过来就是在切换本地代理、处理 Codex 的 /responses 端点时失败了。这说明什么说明真实使用中用户不是简单地装一个工具而是要在一个已经存在多种工具、多个模型、多套配置的环境里让它们互相不打架地协同工作。这就是装配层的价值。单个工具的安装是简单的但当你同时要在 Windows 上用 Claude Code还要在 Ubuntu 上也配一套让 Claude Code 调用 LM Studio 的本地模型让 Codex 接入 DeepSeek在 VS Code 里也能用上这些能力还要处理 npm 的镜像源、环境变量、PowerShell 脚本执行策略这时候问题就从装软件变成了装配一套系统。openrig 这类项目的核心领域就是把散落在各处的配置、脚本、模型接入方式收敛成一套可复现、可迁移、可版本管理的装配方案。它解决的不是能不能用而是能不能稳定地、可重复地用。2.2 YAML 在这套装配体系里扮演的角色热搜词里yolov10 yaml文件怎么创建、rstudio的yaml在哪里、yaml文件、yaml安装反复出现说明 YAML 是这套体系里的关键配置载体。为什么是 YAML 而不是 JSON 或 TOML我的经验是YAML 在表达层级化的配置时可读性明显更好而且支持注释——这一点对需要写大量说明的装配配置来说太重要了。在 openrig 这类方案里YAML 通常承担几个职责模型接入配置定义本地模型或远程模型的 endpoint、模型名、上下文长度、温度等参数工具行为配置定义 Claude Code 或 Codex 的行为比如是否自动执行命令、权限边界环境装配清单声明需要哪些依赖、哪些环境变量、哪些路径我实测下来YAML 最容易出问题的地方是缩进。它用空格缩进表达层级一个 Tab 混进去就可能解析失败而且报错信息往往不直观。所以如果你在写 openrig 相关的配置文件建议在编辑器里把 Tab 自动转成 2 个空格并且开启 YAML 语法校验。2.3 npm 生态装配的最后一公里npm安装、npm卸载全局包、npm环境变量path配置、npm 国内源、npm镜像源地址、npm 淘宝源、发布npm包——这一串热搜词说明openrig 的分发和安装大概率是走 npm 的。这很合理因为 Claude Code、Codex CLI 这类工具本身就是 Node.js 生态的产物用 npm 全局安装是最自然的路径。但 npm 在 Windows 上的坑特别多热搜里npm : 无法加载文件 d:\program files\nodejs\npm.ps1,因为在此系统上禁止运行脚本和npm : 无法加载文件 c:\program files\nodejs\npm.ps1出现了两次说明这是高频问题。这个问题的本质是 PowerShell 的执行策略Execution Policy默认禁止运行脚本而 npm 在 Windows 上会生成一个npm.ps1脚本供 PowerShell 调用。解决办法不是去改 npm而是调整 PowerShell 的执行策略或者改用 CMD。3. 装配前的环境盘点别急着敲命令3.1 Node.js 与 npm 的版本对齐在动手之前我强烈建议先做一次环境盘点。很多人一上来就npm install -g结果装到一半报错回头才发现 Node 版本不对。Claude Code 和 Codex CLI 对 Node 版本通常有最低要求我见过的最低是 Node 18新版本工具可能要求 Node 20 甚至更高。盘点命令很简单node -v npm -v如果 Node 版本太低不要用系统包管理器随便升级容易把系统里其他依赖 Node 的东西搞坏。我的做法是用版本管理工具比如 Windows 上用 nvm-windowsLinux/macOS 上用 nvm。这样可以在不同项目间切换 Node 版本互不影响。提示如果你在 Windows 上遇到npm.ps1 无法加载的报错先别怀疑 Node 装坏了。用管理员身份打开 PowerShell执行Get-ExecutionPolicy看看当前策略。如果是 Restricted可以执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser来放开当前用户的脚本执行权限。改完之后重开终端再试。3.2 镜像源国内环境的必要优化npm 国内源、npm镜像源地址、npm 淘宝源这些词高频出现说明国内用户装包时网络是个现实问题。默认的 npm 源在国内访问经常超时导致安装中断。我的建议是装包前先切源npm config set registry https://registry.npmmirror.com装完之后如果你要发布自己的包记得切回官方源否则会发布失败。可以用npm config get registry随时确认当前源。这里有个细节有些工具在安装时会去拉 GitHub 上的二进制文件这时候光切 npm 源是不够的还需要配置对应的镜像环境变量。具体变量名取决于工具通常在它的安装文档里会说明。我踩过的坑是npm 包装好了但工具首次运行时要下载一个运行时二进制卡在那里半天不动最后发现是二进制下载源没配。3.3 环境变量 PATH 的配置逻辑npm环境变量path配置这个词说明很多人装完全局包之后发现命令找不到。npm 全局安装的包可执行文件会被放到一个全局 bin 目录里这个目录必须在系统的 PATH 中否则你在任何地方敲命令都会提示不是内部或外部命令。查看全局 bin 目录npm config get prefix在 Windows 上全局包的可执行文件通常在%APPDATA%\npm下在 Linux/macOS 上通常在/usr/local/bin或~/.npm-global/bin。确认这个路径在 PATH 里是装完包能直接用的前提。我个人的习惯是装完一个全局 CLI 工具后立刻新开一个终端窗口敲一下工具名 --version。如果找不到先查 PATH别急着重装。重装解决不了 PATH 问题只会浪费时间。4. Claude Code 与 Codex 的本地接入实操4.1 Claude Code 的安装与首次配置claude code安装、claude code下载、claude code windows、claude code 安装、安装claude code——这一组词说明安装本身是大家最关心的第一步。基于 npm 生态的常见做法Claude Code 的安装大概率是这样npm install -g anthropic-ai/claude-code装完之后第一次运行需要做认证配置。热搜里your organization has disabled claude subscription access for claude code这个报错很典型意思是你的组织禁用了 Claude 订阅对 Claude Code 的访问。这不是安装问题是账号权限问题需要联系组织管理员或者换一个个人账号。claude code使用、claude code如何直接执行终端命令这两个词反映了使用层面的核心诉求。Claude Code 的一个关键能力是它能直接在你的终端里执行命令、读写文件。这个能力很强但也意味着权限边界要设清楚。我的经验是在陌生项目里第一次用先让它只读确认它的行为符合预期后再逐步放开写和执行权限。vscode配置claude code、claude code for vs code、claude code桌面版说明它还有编辑器集成形态。VS Code 集成的价值在于你不用在终端和编辑器之间来回切AI 能直接看到你当前打开的文件和光标位置上下文更准。配置方式通常是在 VS Code 里装对应扩展然后在扩展设置里填入认证信息或指向本地配置。4.2 让 Claude Code 调用 LM Studio 的本地模型claude code 调用lmstudio的本地模型这个搜索词特别有意思它代表了一类明确需求我不想用云端模型我想用自己机器上跑的模型。LM Studio 是一个可以在本地加载和运行大模型的桌面工具它启动后会暴露一个兼容 OpenAI 接口的本地服务默认地址通常是http://localhost:1234/v1。要让 Claude Code 走本地模型核心是配置它的模型 endpoint。具体做法取决于 Claude Code 是否支持自定义 base URL。如果支持你需要在配置里把 API base 指向 LM Studio 的地址把模型名填成你在 LM Studio 里加载的模型标识。如果不支持自定义 endpoint那就需要借助一个中间层做协议转换——这也是热搜里cc switch local proxy failed while handling codex endpoint /responses这类报错的来源中间层在处理请求转发时出了问题。我实测这类方案时最容易出问题的地方有三个模型名不匹配LM Studio 里加载的模型标识和你配置里填的必须完全一致大小写都不能错上下文长度本地模型的上下文窗口通常比云端小配置里如果声明了过大的上下文请求会被截断或报错接口兼容性不是所有本地服务都完整实现了 OpenAI 接口的所有字段某些工具会发送一些可选字段本地服务不认识就直接报错排查这类问题的思路是先用 curl 直接打本地服务的接口确认它能正常返回再让上层工具去连。这样能把本地服务的问题和上层工具的问题分开。4.3 Codex 接入 DeepSeek 的配置路径codex接入deepseek、codex cli、codex使用教程、codex安装教程、codex安装包、codex下载、codex官网下载、codex登录——Codex 这一组词的热度不亚于 Claude Code。Codex CLI 是另一款终端里的 AI 编程助手接入 DeepSeek 的逻辑和接入本地模型类似把它的模型 endpoint 指向 DeepSeek 的 API 地址填入对应的 API Key选择正确的模型名。配置通常写在 YAML 或 JSON 配置文件里形如model: provider: deepseek base_url: https://api.deepseek.com api_key: ${DEEPSEEK_API_KEY} model_name: deepseek-chat这里用环境变量引用 API Key 是个好习惯避免把密钥硬编码进配置文件然后不小心提交到仓库。codex无法加载组织设置这个报错说明 Codex 也有组织级的配置管理如果组织策略限制了某些模型或某些行为本地配置可能被覆盖。遇到这种问题先确认是不是组织策略在起作用再排查本地配置。codex破甲这个词我不建议深究它通常指绕过某些限制的非正规做法。从工程角度我更推荐在合规范围内使用工具把精力放在提升实际效率上而不是折腾这些边缘操作。5. 装配过程中最容易翻车的几个环节5.1 PowerShell 脚本执行策略Windows 用户的第一道坎前面提到的npm.ps1 无法加载是 Windows 用户装 npm 全局包时的经典拦路虎。我把完整的排查链路写出来方便你复现第一步确认报错原文。如果提示因为在此系统上禁止运行脚本那就是执行策略问题。第二步查看当前策略Get-ExecutionPolicy -List第三步针对当前用户放开Set-ExecutionPolicy RemoteSigned -Scope CurrentUser第四步重开终端验证npm -v是否正常。为什么用RemoteSigned而不是Unrestricted因为RemoteSigned允许本地脚本运行但从网络下载的脚本需要签名安全性更好。-Scope CurrentUser表示只影响当前用户不需要管理员权限也不会影响系统其他用户。注意如果你在公司电脑上执行策略可能是 IT 部门统一管控的改不动。这种情况下可以改用 CMD 而不是 PowerShell 来运行 npm 命令CMD 不受 PowerShell 执行策略影响。5.2 全局包冲突与 peer dependency 警告npm warn eresolve overriding peer dependency这个警告在装 AI 工具链时很常见。它的意思是npm 在解析依赖树时发现某个包的 peer dependency 版本和实际安装的版本不一致于是做了覆盖。大多数情况下这只是警告不影响使用。但如果工具运行时报模块找不到或版本不兼容就要认真对待了。我的处理原则是如果只是警告工具能正常跑先不管它如果工具报错先看报错涉及的包用npm ls 包名看实际装的版本需要精确控制版本时用npm install -g 包名版本号指定版本npm卸载全局包也是个实用操作命令是npm uninstall -g 包名。当你装了两个功能重叠的工具导致命令冲突时卸载是必要的。卸载后记得确认对应的可执行文件也从全局 bin 目录里消失了。5.3 本地代理转发失败的定位方法回到cc switch local proxy failed while handling codex endpoint /responses这个报错。它描述的是一个代理层在转发 Codex 的/responses请求时失败了。这类问题的定位我总结了一个从下往上的排查顺序排查层级检查内容常用手段本地模型服务服务是否启动、端口是否监听curl http://localhost:端口/v1/models代理层代理是否运行、转发规则是否正确看代理日志、确认目标地址上层工具endpoint 配置是否匹配代理地址检查配置文件里的 base_url协议兼容请求字段是否被目标服务支持对比请求体和目标服务文档从下往上排查的好处是每一层都确认无误后再往上走避免在多层都可能有问题时瞎猜。我见过太多人一上来就改上层工具的配置结果问题其实在本地服务根本没启动。6. 装完之后怎么验证一套可复用的自检清单6.1 命令可用性验证装完任何 CLI 工具第一件事是验证命令能被找到claude --version codex --version如果提示找不到命令回到第 3.3 节检查 PATH。如果提示版本号说明安装和 PATH 都没问题。6.2 认证与模型连通性验证命令能用不代表能干活。下一步是验证认证和模型连通性。对于接入远程 API 的工具可以发一个最简单的请求看能否拿到返回。对于接入本地模型的工具先确认本地服务在跑再让工具发一个测试请求。我习惯用一个最小任务来验证让工具读一个文件、总结一句话。这个任务足够简单如果它连这个都做不了说明配置还有问题如果它能做说明基本链路是通的。6.3 配置文件的可迁移性检查openrig 这类方案的价值之一是可迁移。所以装好之后我会做一次迁移演练把配置文件复制到另一台机器或者另一个目录看能不能直接跑起来。如果跑不起来说明配置里混入了机器相关的硬编码路径或密钥需要抽出来。这个演练能暴露很多隐藏问题比如配置文件里写了绝对路径换机器就失效API Key 硬编码在配置里迁移时泄露风险依赖了某个只在当前机器上装了的全局包把这些都处理干净你的装配方案才算真正可复现。7. 我在实际装配中攒下的几条经验折腾这类环境装配最深的体会是问题往往不在工具本身而在工具之间的缝隙里。Claude Code 单独装没问题Codex 单独装也没问题但当你让它们共享同一套模型配置、同一个代理层、同一份环境变量时冲突就来了。所以我的建议是每接入一个新工具都先让它独立跑通再考虑和已有工具整合。整合时一次只改一个变量改完立刻验证出问题能快速定位是哪个改动引起的。另一个经验是关于配置文件的版本管理。我会把 openrig 相关的配置文件放进一个独立的 git 仓库密钥用环境变量或本地未跟踪的文件管理。这样换机器时clone 下来、填上密钥、跑一遍安装脚本环境就回来了。这比每次手动重配省太多时间。最后说一个容易被忽略的点日志。这类工具出问题时报错信息往往很简短真正的线索在日志里。养成出问题先看日志的习惯比在网上搜报错原文高效得多。日志里通常能看到完整的请求、响应和错误堆栈定位问题的速度会快很多。至于 openrig 后续还能怎么扩展我个人的想法是如果它能把不同工具的配置抽象成统一的 schema再提供一套校验和迁移工具那对多工具协同的场景会非常有价值。不过这属于我基于当前需求的推测具体还得看项目本身怎么演进。