openrig 声明式装配：统一管理 Claude Code 与 Codex 的 AI 编码工具链-育师

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 命令或者 JSON？

YAML 的优势在于它对人友好。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

项目级配置，在项目根目录建.npmrc：

registry=https://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 脚本暴露的。解决办法是调整执行策略，用管理员身份打开 PowerShell：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

RemoteSigned的含义是：本地写的脚本可以跑，从网络下载的脚本需要有签名。对开发机来说这是个比较平衡的选择。改完之后用Get-ExecutionPolicy -Scope CurrentUser确认一下。

如果你不想动执行策略，还有个绕法：改用 CMD 而不是 PowerShell，或者直接用npm.cmd。但这些都是权宜之计，长期看还是把执行策略配好更省心。

提示：改执行策略属于系统级设置，改之前确认你理解它的含义。RemoteSigned是开发场景下比较稳妥的选项，不要图省事直接设成Unrestricted。

3.3 环境变量 PATH 配置与全局包管理

npm 全局安装的包，可执行文件会放到全局bin目录。这个目录必须在 PATH 里，否则你装完了在终端里敲命令会提示"不是内部或外部命令"。

查全局目录：

npm config get prefix

Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm，Linux/macOS 上通常是/usr/local或用户目录下的某个位置。把这个路径下的bin（Windows 上是根目录本身）加进 PATH。

卸载全局包用：

npm uninstall -g 包名

这里有个经验：装 AI 编码工具的时候，尽量用全局安装，因为你要在任意目录下调用它。但全局装多了容易乱，建议定期用npm list -g --depth=0看看装了哪些全局包，把不用的清掉。我见过有人全局装了几十个包，最后自己都记不清哪个是干嘛的。

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 编码工具本身在快速迭代，配置方式也会变，但"用配置管理复杂度"这个原则不会过时。

我个人在实际操作中的体会是，这类装配工具最大的价值不在于省了多少敲命令的时间，而在于它逼你把"我到底想让工具怎么跑"这件事想清楚、写下来。很多时候配置出问题，根因是你自己都没想明白要接哪个端点、用哪个模型。写配置的过程，其实就是理清需求的过程。最后再分享一个小技巧：每次改完配置，别急着全量验证，先跑一个最小请求确认链路通了，再逐步加复杂度，这样出问题的时候排查范围小得多。