1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个项目名我脑子里蹦出来的第一反应是open加rig——rig 在英文里是装配、搭台子的意思搞过硬件或者做实验的人对这个词不陌生搭一套测试台架就叫 rig。放到 AI 编程工具这个语境里openrig想干的事情其实很直白把散落一地的 AI 编码助手配置、模型接入、代理转发、环境变量这些东西用一个统一的、开放的、可版本管理的方式装配起来。为什么会有这个需求你只要真正在本地同时用过 Claude Code、Codex 这类命令行 AI 编码工具就明白痛点在哪了。这些工具各自有各自的配置文件格式、各自的模型端点约定、各自的登录态管理方式。Claude Code 走 Anthropic 的接口Codex 走 OpenAI 的/responses端点你想让它们都指向本地跑的模型服务或者指向某个兼容层就得手动改配置、设环境变量、起代理。改一次两次还行工具一多、机器一换、团队一协作立刻就乱套了。openrig的核心价值就在这它把AI 编码工具怎么接、接哪个模型、走什么端点、用什么参数这件事抽象成一份声明式的配置通常就是 YAML 文件。你写一份 rig 配置它负责把 Claude Code、Codex 这些工具按你的意图装配好。这跟当年 Docker Compose 把一堆docker run命令收敛成一份docker-compose.yml是同一个思路——把命令式的、易错的手工操作变成声明式的、可复现的配置。适合谁来参考这篇文章三类人。第一类是本机同时装了 Claude Code 和 Codex、被多套配置折磨的开发者第二类是团队里负责统一开发环境、想让新人一条命令就把 AI 编码工具跑起来的人第三类是想把 AI 编码工具接到自建模型服务上、需要精细控制端点和参数的进阶用户。如果你只是偶尔用用网页版这篇可能对你偏重了但如果你天天在终端里跟这些工具打交道下面的内容应该能帮你省下不少折腾时间。需要先说明一点openrig这类工具的具体实现细节官方文档往往更新很快本文里涉及的具体配置字段、命令参数是基于这类声明式装配工具的通用实践和我自己踩坑经验做的合理推演你在实际使用时以项目最新文档为准但背后的思路和排错方法是通用的。2. 核心设计思路拆解为什么是 YAML为什么是装配而不是安装2.1 声明式配置为什么比一堆命令行参数靠谱先聊一个根本问题为什么这类工具几乎都选 YAML 作为配置载体而不是让你写一串 shell 命令或者 JSONYAML 的优势在于它对人友好。JSON 那套大括号加引号的写法写配置的时候少个逗号就报错多行字符串处理起来也难受。YAML 用缩进表达层级支持注释写模型端点、环境变量、工具开关这些东西读起来一目了然。你去看现在主流的 AI 工具链从模型部署到工作流编排YAML 几乎是事实标准。热搜里那一堆yolov10 yaml 文件怎么创建rstudio 的 yaml 在哪里其实反映的是同一个现象只要一个工具需要用户描述我要什么YAML 就是首选。但 YAML 也有它自己的坑这个后面排错章节会细讲最典型的就是缩进敏感和类型推断。比如version: 1.0会被解析成浮点数on: true里的on在某些解析器里会被当成布尔值true。这些坑不踩一遍是记不住的。声明式配置真正的价值在于它把意图和执行分开了。你描述的是我要 Claude Code 用这个模型、走这个端点至于具体怎么设环境变量、怎么起代理、怎么改哪个文件交给工具去做。这样一来配置可以进 Git、可以 code review、可以在不同机器上复现。命令式操作做不到这一点——你今天敲的命令明天就忘了换台机器又得重新摸索。2.2 装配这个隐喻背后的工程考量openrig用rig这个词我觉得是刻意的。装配rigging意味着几件事组件是可替换的连接关系是显式的整体是可拆卸的。组件可替换对应的是模型和工具的解耦。今天你用某个云端模型明天想换成本地跑的模型理想情况下只改配置里的一行不用动工具本身的任何东西。连接关系显式对应的是端点、密钥、超时这些参数都写在明面上而不是藏在某个工具的默认行为里。可拆卸对应的是你能干净地卸载、切换、回滚不会在系统里留下一堆改过的配置文件和环境变量。这三点恰恰是手工配置最缺的。手工配置的典型状态是你改了 Claude Code 的配置指向本地模型过两天想切回去忘了当初改了哪几个地方或者你给 Codex 设了个环境变量结果它跟另一个工具的环境变量打架了。装配式工具要解决的就是这种配置漂移。2.3 和 npm 生态的关系为什么绕不开 npm热搜里npm相关的词占了很大比重——npm 安装、npm 国内源、npm 卸载全局包、npm 镜像源地址、npm : 无法加载文件 ... npm.ps1。这不是偶然的。Claude Code、Codex 这类工具很多都是通过 npm 分发的openrig如果要做工具装配大概率也绕不开 npm 这个包管理入口。理解这一点很重要openrig不是要取代 npm而是在 npm 装好工具之后负责配置和编排这一层。你可以把它理解成 npm 管装什么openrig 管怎么接、怎么跑。两者是上下游关系。所以后面讲实操的时候npm 环境的正确配置是前置条件npm 本身出问题openrig 再牛也跑不起来。3. 环境准备把 npm 和 Node 这层地基打牢3.1 npm 安装与国内源配置的实操细节不管你最终用不用 openrig只要涉及 Claude Code、Codex 这类工具npm 环境是第一步。国内网络环境下默认源拉包慢是常态配国内镜像源几乎是必做动作。配置镜像源有两种粒度。全局配置npm config set registry https://registry.npmmirror.com项目级配置在项目根目录建.npmrcregistryhttps://registry.npmmirror.com我个人的习惯是全局配镜像源但保留一个项目级.npmrc用于特殊场景。为什么要留项目级因为有些包在镜像源上同步有延迟遇到拉不到最新版本的情况临时在项目里切回官方源排查比全局改来改去干净。验证配置是否生效npm config get registry这条命令应该输出你设置的镜像地址。如果输出还是默认的https://registry.npmjs.org/说明配置没写对检查一下是不是写到了错误的配置文件里。注意镜像源不是越多越好也不是所有包都能在镜像上找到。遇到404或者版本对不上第一反应应该是切回官方源验证而不是怀疑包本身有问题。3.2 Windows 上 npm.ps1 无法加载的经典报错热搜里反复出现npm : 无法加载文件 c:\program files\nodejs\npm.ps1因为在此系统上禁止运行脚本这个报错我见过太多次了几乎每个在 Windows 上用 PowerShell 装 Node 工具的人都会撞上。根因是 PowerShell 的执行策略Execution Policy默认禁止运行脚本而 npm 在 Windows 上是通过npm.ps1这个 PowerShell 脚本暴露的。解决办法是调整执行策略用管理员身份打开 PowerShellSet-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedRemoteSigned的含义是本地写的脚本可以跑从网络下载的脚本需要有签名。对开发机来说这是个比较平衡的选择。改完之后用Get-ExecutionPolicy -Scope CurrentUser确认一下。如果你不想动执行策略还有个绕法改用 CMD 而不是 PowerShell或者直接用npm.cmd。但这些都是权宜之计长期看还是把执行策略配好更省心。提示改执行策略属于系统级设置改之前确认你理解它的含义。RemoteSigned是开发场景下比较稳妥的选项不要图省事直接设成Unrestricted。3.3 环境变量 PATH 配置与全局包管理npm 全局安装的包可执行文件会放到全局bin目录。这个目录必须在 PATH 里否则你装完了在终端里敲命令会提示不是内部或外部命令。查全局目录npm config get prefixWindows 上通常是C:\Users\你的用户名\AppData\Roaming\npmLinux/macOS 上通常是/usr/local或用户目录下的某个位置。把这个路径下的binWindows 上是根目录本身加进 PATH。卸载全局包用npm uninstall -g 包名这里有个经验装 AI 编码工具的时候尽量用全局安装因为你要在任意目录下调用它。但全局装多了容易乱建议定期用npm list -g --depth0看看装了哪些全局包把不用的清掉。我见过有人全局装了几十个包最后自己都记不清哪个是干嘛的。4. openrig 配置实操从一份 YAML 到跑起来的工具链4.1 配置文件的结构设计假设openrig的配置是一份 YAML它的结构大概率会分成几块全局设置、模型端点定义、工具定义。我按这类工具的通用设计思路给你拆一个可参考的骨架。version: 1 # 全局设置 settings: log_level: info config_dir: ~/.openrig # 模型端点定义 endpoints: local-model: base_url: http://127.0.0.1:1234/v1 api_key: sk-local timeout: 120 cloud-model: base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} timeout: 60 # 工具定义 tools: claude-code: endpoint: local-model model: my-local-model env: ANTHROPIC_BASE_URL: ${endpoint.base_url} codex: endpoint: cloud-model model: gpt-5.6-sol env: OPENAI_BASE_URL: ${endpoint.base_url}这个骨架里几个设计点值得说。第一端点和工具分开定义一个端点可以被多个工具复用改端点只改一处。第二api_key用${CLOUD_API_KEY}这种环境变量引用避免密钥硬编码进配置文件——配置文件是要进 Git 的密钥绝对不能进。第三每个工具可以有自己的env覆盖因为不同工具认的环境变量名不一样。4.2 端点配置base_url、api_key、timeout 三件套端点配置是整份配置的核心因为 AI 编码工具能不能跑起来八成问题出在端点上。base_url是模型服务的地址。这里有个高频坑很多兼容层要求base_url带上/v1后缀有些又不带。Claude Code 走 Anthropic 协议Codex 走 OpenAI 的/responses端点两者对路径的约定不同。热搜里那条cc switch local proxy failed while handling codex endpoint /responses就是典型的端点路径不匹配——代理层没正确处理 Codex 请求的/responses路径。我的经验是配置端点时先把工具的默认端点记下来然后逐个字段替换而不是一上来就全改。这样出问题的时候能快速定位是哪个字段改错了。api_key的处理前面说了用环境变量引用。本地模型服务通常不校验密钥随便填个sk-local之类的占位符就行但字段不能空很多客户端在密钥为空时会直接报错。timeout这个参数容易被忽略但很关键。本地模型推理慢尤其是大模型跑在消费级显卡上一个复杂请求几十秒很正常。默认超时往往只有 30 秒不改的话你会频繁遇到请求超时然后误以为是模型或网络问题。本地端点建议设到 120 秒以上。4.3 工具接入Claude Code 和 Codex 的差异处理Claude Code 和 Codex 虽然都是命令行 AI 编码工具但接入方式差别不小。Claude Code 主要通过环境变量控制端点典型的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。你想让它指向本地模型就把ANTHROPIC_BASE_URL设成本地服务的地址。但要注意Claude Code 期望的是 Anthropic 的 API 协议如果你的本地服务只提供 OpenAI 兼容协议中间就需要一个协议转换层。这是很多人卡住的地方——以为改个地址就行结果协议对不上。Codex 走 OpenAI 协议环境变量通常是OPENAI_BASE_URL和OPENAI_API_KEY。热搜里codex 接入 deepseek、codex 无法加载组织设置、your organization has disabled claude subscription access这些反映的是 Codex 在账号体系和模型支持上的限制。Codex 对模型名有校验你填一个它不认识的模型名会直接报the gpt-5.6-sol model is not supported。所以接第三方模型时模型名要么用兼容层映射要么确认工具支持自定义模型名。openrig在这里的价值就体现出来了它把Claude Code 需要 Anthropic 协议、Codex 需要 OpenAI 协议这种差异通过端点定义和工具配置的组合处理掉。你不需要记住每个工具认哪个环境变量配置里声明清楚就行。4.4 用 openrig 装配的完整流程把上面的东西串起来一个完整的装配流程大概是这样确认 npm 和 Node 环境正常镜像源配好。通过 npm 全局安装 Claude Code、Codex 等目标工具。准备模型服务确认它的协议类型Anthropic 兼容还是 OpenAI 兼容和端点地址。编写 openrig 的 YAML 配置定义端点和工具。执行 openrig 的装配命令让它把配置应用到各个工具。逐个验证工具能否正常调用模型。第 5 步的具体命令取决于 openrig 的实际接口可能是openrig apply、openrig up之类。这类工具通常还提供openrig status查看当前装配状态、openrig down卸载配置。装配类工具的命令设计一般会向 Docker Compose 看齐因为用户对这个心智模型最熟悉。第 6 步的验证很关键别装完就以为成了。分别跑一下 Claude Code 和 Codex 的最简请求看返回是否正常。如果某个工具报错先看它的日志再看 openrig 的日志最后看模型服务的日志从下游往上游排查。5. 常见问题与排查技巧实录5.1 端点类问题速查端点相关的问题占了实际排错的一大半我整理成一张表方便对照。现象可能原因排查方向请求超时timeout 设太短本地端点调到 120s 以上404 找不到路径base_url 缺或多/v1对照工具默认端点逐字段核对401 未授权api_key 为空或错误检查环境变量是否注入成功协议不匹配工具要 Anthropic服务给 OpenAI加协议转换层模型不支持模型名不在工具白名单用兼容层映射模型名这张表里的每一条我基本都踩过。最坑的是协议不匹配因为报错信息往往很含糊不会直接告诉你协议不对而是给你一个解析失败或者格式错误。判断方法很简单看你的模型服务文档确认它提供的是哪种协议再看工具文档确认它期望哪种协议。两者不一致中间就必须有转换。5.2 配置类问题的隐蔽陷阱YAML 配置的坑前面提了缩进和类型推断这里展开说几个具体的。缩进问题YAML 用空格缩进不能用 Tab。混用 Tab 和空格解析器会报错而且报错位置经常不准让你以为是别的地方有问题。我的习惯是编辑器里把 Tab 自动转成 2 个空格从源头避免。类型推断问题model: 1.0会被解析成数字model: 1.0才是字符串。模型名里带点号或者纯数字的情况不少该加引号就加引号。还有yes、no、on、off这些词在某些 YAML 解析器里会被当成布尔值用作键名或字符串值时一定要加引号。环境变量引用问题${VAR}这种引用如果变量没定义有的工具会报错有的会替换成空字符串。空字符串传给api_key字段就变成前面说的 401 问题。所以配置里引用的环境变量一定要确认在运行环境里存在。5.3 工具侧的典型报错处理npm warn eresolve overriding peer dependency这个警告装包时经常出现。它说的是依赖树里有版本冲突npm 自动帮你选了一个版本。大多数情况下这个警告可以忽略包能正常跑。但如果工具启动就崩那就要认真看这个警告可能是某个关键依赖版本不对。处理办法是看警告里提到的具体包手动在项目里锁定版本。codex 无法加载组织设置和your organization has disabled claude subscription access这类属于账号和权限层面的问题不是配置能解决的。遇到这种先确认你的账号状态和订阅情况再看是不是工具版本和账号体系不匹配。这类问题排查起来最费劲因为报错信息指向的是权限但根因可能在账号配置或者区域设置上。cc switch local proxy failed while handling codex endpoint /responses这条是代理层处理 Codex 请求时失败。核心是代理没正确识别/responses这个路径。如果你自己搭了代理检查路由规则里有没有覆盖这个路径如果用现成的兼容层确认它支持 Codex 的端点约定。5.4 我踩过的几个坑和独家经验第一个坑以为改了环境变量就生效。环境变量是在进程启动时读取的你改了配置文件或者 shell 里的变量已经运行的终端会话不会自动更新。改完要么重开终端要么手动source一下配置文件。我因为这个浪费过半小时一直以为配置写错了。第二个坑多个工具的环境变量互相污染。Claude Code 和 Codex 如果都读OPENAI_BASE_URL之类的通用变量你为 A 工具设的值可能影响 B 工具。解决办法是尽量用工具专属的变量名或者在 openrig 配置里给每个工具单独指定 env让装配过程隔离它们。第三个坑本地模型服务的并发限制。本地跑模型并发能力有限你同时开 Claude Code 和 Codex 发请求可能把服务打满表现为随机超时。这时候不是配置问题是资源问题。要么串行使用要么给服务加队列。第四个坑配置文件里的相对路径。config_dir这类路径用相对路径在不同工作目录下执行会指向不同位置。统一用绝对路径或者~开头的家目录路径能避免很多明明配了却找不到的问题。6. 把 openrig 用顺手的几个进阶思路6.1 多环境配置的切换策略开发机、测试机、团队共享环境配置往往不一样。openrig 这类工具通常支持多份配置文件或者配置覆盖。我的做法是基础配置放一份base.yaml各环境用override文件覆盖差异部分。比如本地开发覆盖端点指向本地模型团队环境覆盖端点指向共享服务。这样切换环境就是换一个 override 文件的事不用维护多份几乎重复的完整配置。配置的复用和差异分离是声明式工具最该发挥价值的地方。6.2 配置进版本控制与密钥管理配置文件进 Git 是必须的但密钥不能进。前面说的环境变量引用是基础做法。更进一步可以用.env文件管理密钥.env加进.gitignore配置里引用.env里的变量。团队协作时每个人维护自己的.env配置文件共享。再讲究一点可以用密钥管理工具但那是团队规模上来之后的事。个人和小团队.env加环境变量引用足够用了。6.3 和编辑器集成的注意事项热搜里vscode 配置 claude code、claude code for vs code、vscode 接入 claude code这些说明很多人是在 VS Code 里用这些工具的。编辑器集成有个特点编辑器启动的终端环境变量可能和你在系统终端里设的不一样。VS Code 的集成终端继承的是 VS Code 进程的环境而不是你登录 shell 的环境。所以如果你在系统终端里配好了环境变量工具能跑但在 VS Code 里跑不起来八成是环境变量没被 VS Code 继承。解决办法是在 VS Code 的设置里配置终端环境变量或者用 openrig 这类工具把配置写到工具自己的配置文件里而不是依赖 shell 环境变量。这也是装配式工具的一个隐性优势它把配置落到工具层面减少对 shell 环境的依赖。6.4 后续可以扩展的方向openrig这类工具用顺了之后可以往几个方向扩展。一是把模型服务的健康检查纳入装配流程装配完自动验证端点可达。二是把配置模板化团队新人一条命令生成自己的配置。三是把装配状态纳入监控端点挂了能及时知道。这些扩展不一定都要做但思路是一致的把手工的、易错的、靠记忆的操作逐步收敛到声明式配置和自动化流程里。AI 编码工具本身在快速迭代配置方式也会变但用配置管理复杂度这个原则不会过时。我个人在实际操作中的体会是这类装配工具最大的价值不在于省了多少敲命令的时间而在于它逼你把我到底想让工具怎么跑这件事想清楚、写下来。很多时候配置出问题根因是你自己都没想明白要接哪个端点、用哪个模型。写配置的过程其实就是理清需求的过程。最后再分享一个小技巧每次改完配置别急着全量验证先跑一个最小请求确认链路通了再逐步加复杂度这样出问题的时候排查范围小得多。