1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件测试架或者开源机械臂项目毕竟 rig 这个词在工程领域通常指“台架、装置”。但把 openrig 和 Claude Code、Codex、YAML、Node.js 这几个词放在一起方向就清楚了——这是一个围绕 AI 编程助手做统一配置与编排的开源工具核心思路是用一份 YAML 描述文件把 Claude Code、Codex 这类命令行 AI 编码代理的模型接入、参数、工作目录、权限策略统一管起来。说白了openrig 解决的是一个很现实的痛点现在手上同时用 Claude Code 和 Codex 的人越来越多两个工具各有各的配置文件、各有各的环境变量、各有各的模型接入方式。今天想让 Claude Code 走本地模型明天想让 Codex 接第三方兼容端点后天又要在 VS Code 里切换配置散落在~/.claude、~/.codex、项目根目录、系统环境变量好几个地方改一处忘一处排查起来非常痛苦。openrig 就是把这些散点收敛成一份声明式的 YAML让“换模型、换端点、换工作区”变成改几行配置的事。它适合谁三类人最值得看一是同时使用多个 AI 编码 CLI 的重度用户二是需要在团队内统一 AI 助手配置的工程负责人三是想接本地模型或第三方兼容端点、又不想每次手改环境变量的折腾党。如果你只是偶尔用一下网页版对话这个项目对你价值不大但只要你每天在终端里跟 Claude Code 或 Codex 打交道openrig 这类工具能省下大量重复劳动。需要先说明一点openrig 目前属于相对小众的工具公开文档不算特别完整很多细节需要结合 Claude Code 和 Codex 各自的官方配置约定去推断。下面我讲的内容一部分来自项目本身的定位一部分是基于我实际配置这两个 CLI 的经验做的合理补全凡是推断的地方我都会标出来你照着做的时候以自己环境的实际报错为准。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选 YAML 作为配置载体这个决定我认为是对的理由有三层。第一层是可读性。AI 编码助手的配置里经常要写多行提示词、多行系统指令、带缩进的权限规则JSON 处理多行字符串要靠\n转义写起来反人类TOML 虽然对多行字符串友好但嵌套结构一深就变得啰嗦。YAML 的块标量|和天然适合写提示词缩进即层级人眼扫一遍就知道结构。第二层是生态惯性。Claude Code 和 Codex 本身就在用 YAML 或类 YAML 的配置风格比如很多项目的 CI 配置、模型参数文件都是 YAML。openrig 顺着这个惯性走用户迁移成本最低。你去看热词里“yolov10 yaml 文件怎么创建”“rstudio 的 yaml 在哪里”说明 YAML 已经是跨领域配置的事实标准大家对这个格式不陌生。第三层是合并与覆盖的便利。openrig 这类工具通常需要支持“全局配置 项目级配置”的层叠覆盖YAML 的映射结构做深合并deep merge非常自然。全局定义默认模型项目里只覆盖model字段其余继承这种模式用 YAML 表达最干净。注意YAML 对缩进极其敏感Tab 和空格混用会直接报解析错误。我踩过的坑是复制别人的配置片段时带进了 Tab报错信息只提示“mapping values are not allowed here”排查了半小时。建议编辑器统一设置“Tab 转 2 空格”。2.2 为什么依赖 Node.js 运行时热词里反复出现“node.js 安装”“node.js 是干什么的”“node.js LTS 下载”这不是偶然。Claude Code 和 Codex 的 CLI 都是 Node.js 生态的产物openrig 作为编排层大概率也是 Node.js 实现或者通过 npm 分发的。Node.js 在这里扮演的角色是“运行时 包管理 进程编排”。openrig 需要做几件事读取 YAML 配置、解析成对象、根据配置生成或修改 Claude Code / Codex 的配置文件、可能还要拉起子进程去执行 CLI。这些活儿 Node.js 干起来很顺手child_process模块管进程fs管文件js-yaml管解析一套下来没有短板。版本选择上我强烈建议用 LTS 版本。热词里有个报错很典型“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”这就是版本号写错或者源里没有对应版本导致的。稳妥做法是去 Node.js 官网下载 LTS 长期支持版或者用 nvm 管理多版本。截至我写这篇内容时Node.js 20.x 和 22.x 是主流 LTS 线选这两个大版本基本不会踩兼容性坑。# 用 nvm 安装并切换 LTS 版本推荐 nvm install --lts nvm use --lts node -v npm -v如果你在 Ubuntu 上也可以直接用 NodeSource 的源装但要注意别装成非 LTS 的奇数版本。Windows 用户直接去官网下.msi安装包最省事安装时勾选“Add to PATH”否则后面命令行里找不到node和npm。2.3 统一编排的价值在哪里单独看 Claude Code 或 Codex每个都有自己的配置方式。Claude Code 走~/.claude/settings.json或环境变量Codex 走~/.codex/config之类的路径。问题在于当你两个都用还要在多个项目间切换时配置会变成一团乱麻。openrig 的价值是把“配置源”和“配置目标”解耦。你在 openrig 的 YAML 里声明“我要用哪个模型、哪个端点、哪个工作目录、哪些权限”openrig 负责把这些翻译成各个 CLI 认识的形式。这样带来三个好处一是单一事实来源改一处全生效二是可版本化YAML 文件可以进 Git团队共享三是可切换改一行provider就能从云端模型切到本地模型。这个设计思路和热词里“cc switch 接入 deepseek、qwen、glm 等模型”是同一个诉求——大家就是想要一个统一的切换开关而不是每次手动改环境变量。3. 核心配置细节与实操要点3.1 openrig 配置文件的结构推断由于 openrig 的公开配置样例有限下面这份结构是我基于 Claude Code 和 Codex 的配置需求反推出来的合理形态你可以把它当作起点再根据实际报错调整。# openrig.yaml version: 1 # 全局默认所有 agent 继承 defaults: workdir: ~/projects log_level: info # 定义可复用的模型端点 providers: local: base_url: http://127.0.0.1:1234/v1 api_key: not-needed model: local-model-name remote: base_url: https://api.example.com/v1 api_key: ${OPENRIG_API_KEY} model: gpt-5.6-sol # 定义每个 AI 编码代理的行为 agents: claude-code: provider: local workdir: ~/projects/web permissions: allow_shell: true allow_write: true codex: provider: remote workdir: ~/projects/api permissions: allow_shell: false allow_write: true这份配置里几个关键点值得展开。providers段落是核心。它把“模型从哪来”抽象成一个命名端点base_url指向兼容 OpenAI 接口的服务api_key支持环境变量插值${OPENRIG_API_KEY}这样密钥不会明文进 Git。热词里“codex 接入 deepseek”“claude code 调用 lmstudio 的本地模型”都是这个机制的应用——只要对方提供兼容端点改base_url和model就行。agents段落把每个 CLI 单独配置。provider字段引用上面定义的端点名workdir指定工作目录permissions控制权限。这里权限设计要特别小心allow_shell: true意味着 AI 可以直接执行终端命令方便但危险后面会专门讲。3.2 环境变量插值与密钥管理配置里写${OPENRIG_API_KEY}这种插值语法是避免密钥硬编码的标准做法。openrig 在解析 YAML 时会把${VAR}替换成环境变量的值如果变量不存在通常会报错或者替换成空字符串具体行为要看实现。我的建议是密钥统一放环境变量配置文件里只留占位符。Linux 和 macOS 在~/.bashrc或~/.zshrc里 exportWindows 用系统环境变量或者.env文件配合 dotenv 加载。# ~/.zshrc 或 ~/.bashrc export OPENRIG_API_KEYsk-xxxxxxxx export OPENRIG_LOCAL_URLhttp://127.0.0.1:1234/v1注意不要把带真实密钥的配置文件提交到公开仓库。我见过有人把api_key直接写进 YAML 推到 GitHub几分钟后就被扫描机器人抓走盗刷。哪怕仓库是私有的也建议用环境变量养成习惯。3.3 工作目录与项目隔离workdir这个字段看着简单实际很关键。AI 编码助手的能力边界很大程度上由工作目录决定——它能读哪些文件、能改哪些文件都受这个目录约束。我的实践是按项目分目录每个项目一份 openrig 配置或者用全局配置加项目级覆盖。比如全局配置里workdir: ~/projects具体项目里覆盖成workdir: ~/projects/my-app。这样 AI 在my-app里干活时不会误伤隔壁项目。如果你同时开多个 AI 助手处理不同项目务必让它们的workdir互不重叠。我踩过的坑是让 Claude Code 和 Codex 同时指向同一个目录结果两边同时改同一个文件产生了冲突还得手动合并。后来改成每个 agent 一个独立目录世界清净了。3.4 权限策略的取舍permissions是安全与效率的平衡点。allow_shell打开AI 能直接跑npm install、git commit、跑测试效率极高但一旦 AI 判断失误也可能执行破坏性命令。allow_write控制文件写入关掉它 AI 只能读不能改适合做代码审查场景。我的建议是分场景配置场景allow_shellallow_write理由日常开发truetrue效率优先配合 Git 兜底代码审查falsefalse只读分析防止误改陌生仓库falsetrue可改但不可执行降低风险生产相关falsefalse绝对只读人工确认每一步提示无论权限怎么配工作目录一定要纳入 Git 版本控制。AI 改错了git diff一看便知git checkout一键回滚。没有版本控制兜底就开allow_shell等于裸奔。4. 完整实操流程与关键环节实现4.1 环境准备Node.js 与包管理器第一步是把 Node.js 环境弄干净。热词里“安装 node.js”“node.js LTS 下载”“node.js 官网下载”出现频率极高说明这一步卡住了不少人。去 Node.js 官网下载 LTS 版本或者用版本管理器。我推荐 nvm因为它能让你在不同项目间切换 Node 版本遇到“这个项目要 18那个要 20”的情况不用重装。# macOS / Linux 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.zshrc # 安装并使用 LTS nvm install --lts nvm alias default lts/* node -v # 应输出 v20.x 或 v22.xWindows 用户如果不想折腾 nvm-windows直接官网下.msi也行安装时记得勾选 PATH。装完在 PowerShell 里node -v验证一下。4.2 安装 Claude Code 与 Codex CLI两个 CLI 的安装方式类似都是通过 npm 全局安装。热词里“claude code 安装”“codex 安装教程”“codex 安装包”都是这个环节。# 安装 Claude Code npm install -g anthropic-ai/claude-code # 安装 Codex CLI包名以官方为准这里示意 npm install -g openai/codex # 验证 claude --version codex --version如果安装过程中报权限错误Linux/macOS 常见不要无脑sudo npm install -g那样会把全局包装到 root 目录后续权限更乱。正确做法是配置 npm 的全局目录到用户空间mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加进~/.zshrc或~/.bashrc重新加载后重装即可。4.3 安装并初始化 openrigopenrig 的安装同样走 npm 生态这是基于其 Node.js 依赖的合理推断npm install -g openrig openrig --version初始化通常在项目目录里执行cd ~/projects/my-app openrig initinit命令一般会生成一份openrig.yaml模板里面带注释说明每个字段怎么填。如果它没有自动生成你就手动创建一份参考第 3 节的配置结构。4.4 配置模型端点并验证连通性配置写完别急着用先验证端点通不通。这一步能省掉后面大量“为什么 AI 不回复”的排查时间。# 测试兼容端点是否可达以本地模型为例 curl http://127.0.0.1:1234/v1/models # 如果返回模型列表 JSON说明端点正常如果端点需要密钥带上 header 测curl -H Authorization: Bearer $OPENRIG_API_KEY \ https://api.example.com/v1/models端点通了再让 openrig 应用配置openrig applyapply命令的作用是把 YAML 翻译成各 CLI 认识的配置。执行后你可以去检查~/.claude和~/.codex下的配置文件有没有被正确更新。如果 openrig 支持--dry-run先跑一次看它打算改什么确认无误再真正应用。4.5 在 VS Code 中联动使用热词里“vscode 配置 claude code”“claude code for vs code”“vscode 接入 claude code”说明很多人想在编辑器里用。思路是openrig 管好 CLI 的配置VS Code 里的插件调用同一个 CLI自然继承配置。具体做法是在 VS Code 的集成终端里直接跑claude或codex它们读的就是 openrig 写好的配置。如果你用的是专门的插件检查插件的设置里有没有指定 CLI 路径或配置文件路径指向 openrig 生成的那份即可。注意VS Code 集成终端的环境变量可能和系统终端不一致尤其是 Windows 上。如果 CLI 在系统终端能用、在 VS Code 里报“找不到命令”多半是 PATH 没继承。重启 VS Code 或者手动在插件设置里补全路径。4.6 切换模型与端点的实操这是 openrig 最爽的场景。假设你白天用云端模型晚上想切本地模型省钱只需要改 YAML 里agents.claude-code.provider的值从remote改成local然后openrig apply。agents: claude-code: provider: local # 从 remote 改成 local如果你经常切换可以准备多份配置片段用命令行参数指定openrig apply --config openrig.local.yaml openrig apply --config openrig.remote.yaml这样一条命令完成切换不用手动编辑任何文件。热词里“cc switch 接入 deepseek、qwen、glm”追求的就是这种一键切换体验。5. 常见问题与排查技巧实录5.1 模型不支持报错怎么破热词里有个很具体的报错“the gpt-5.6-sol model is not supported when using codex with a...”。这类错误的本质是你配置的模型名端点不认识或者该端点不支持这个模型。排查顺序是这样的先用curl打端点的/models接口看返回的模型列表里有没有你写的那个名字。名字必须完全一致大小写、连字符都不能错。如果列表里没有说明要么模型名写错要么这个端点根本不提供该模型。还有一种情况是端点兼容层的问题。有些第三方端点只实现了 OpenAI 接口的子集Codex 调用某些特性比如特定的 function calling 格式时对方不支持就会报“model is not supported”。这时候换个模型或者换回官方端点验证一下就能定位是端点的问题还是配置的问题。5.2 组织权限相关的报错热词里“your organization has disabled claude subscription access for claude code”和“codex 无法加载组织设置”属于账号权限层面的问题。这类报错跟 openrig 配置无关是账号本身的状态问题。遇到这种先确认你的账号是否有对应服务的访问权限。如果是团队账号可能是管理员在组织层面关闭了某个功能的访问。这种情况改配置文件没用得找管理员开通或者换个人账号。我建议在排查配置问题前先用官方默认配置跑一次确认账号本身能用再叠加 openrig 的配置这样能把“账号问题”和“配置问题”分开。5.3 代理与端点连接失败热词里“cc switch local proxy failed while handling codex endpoint /responses”指向的是本地代理转发失败。这类问题的排查思路是分层验证排查层检查内容验证方法网络层端点是否可达curl或ping认证层密钥是否有效带 header 请求协议层路径是否正确检查/v1前缀应用层配置是否生效查看 CLI 日志最常见的原因是路径拼错。很多兼容端点要求/v1/chat/completions但配置里只写了base_urlopenrig 或 CLI 拼接时多一层少一层/v1就 404。仔细核对端点的文档确认 base_url 应该写到哪一级。5.4 Node.js 版本与安装报错“error installing 24.21.0: node.js v24.21.0 is not yet released”这个报错说明有人指定了一个不存在的版本号。Node.js 的版本号是真实存在的具体版本不能随便写。去官网看当前有哪些 LTS 版本或者直接nvm install --lts让工具自己选。另一个常见坑是全局包安装后命令找不到。这通常是 npm 全局 bin 目录不在 PATH 里。用npm config get prefix看全局目录在哪然后把这个目录下的bin加进 PATH。5.5 常见问题速查表现象可能原因解决方向命令找不到PATH 未配置检查 npm 全局 bin 目录YAML 解析失败Tab 与空格混用统一用 2 空格缩进模型不支持模型名错误或端点不支持核对/models列表端点连接失败base_url 路径错误确认/v1层级密钥无效环境变量未加载echo $VAR验证配置不生效未执行 apply重新openrig apply权限被拒账号组织限制联系管理员或换账号文件冲突多 agent 同目录拆分 workdir5.6 我踩过的几个坑第一个坑是配置文件放错位置。openrig 可能同时支持全局配置和项目配置我一开始把项目配置放到了全局目录结果所有项目都受影响。后来搞清楚优先级项目级覆盖全局级就近原则。放对位置后问题消失。第二个坑是环境变量没导出。我在 YAML 里写了${OPENRIG_API_KEY}但忘了在当前 shell 里 exportopenrig 解析时拿到空值请求全部 401。排查时先echo $OPENRIG_API_KEY确认有值再往下查。第三个坑是权限开太大。早期图省事把allow_shell和allow_write全开结果 AI 在一个没纳入 Git 的目录里执行了清理命令删掉了一些临时文件。虽然不致命但吓出一身冷汗。从那以后任何让 AI 碰的目录第一件事就是git init。第四个坑是同时跑两个 agent。有次 Claude Code 和 Codex 都指向同一个项目目录两边同时改package.json一个加依赖一个删依赖最后文件冲突。解决办法是给每个 agent 分配独立的工作副本或者串行使用别让它们同时写同一批文件。6. 进阶玩法与扩展方向6.1 团队共享配置openrig 的 YAML 天然适合进 Git。团队可以维护一份基础配置定义好公司统一的模型端点、权限策略、工作目录规范成员 clone 下来改改个人密钥就能用。这样新人入职不用从零配环境也避免了每个人配置不一致导致的“在我机器上能跑”。做法是把openrig.yaml提交到仓库密钥部分用环境变量占位。再配一份openrig.example.yaml作为模板.gitignore里排除个人覆盖文件。团队约定好字段含义谁要加新端点就提 PR评审后合并。6.2 多环境切换开发、测试、生产用不同的模型端点这在企业里很常见。openrig 可以用多份配置文件实现openrig apply --config configs/dev.yaml openrig apply --config configs/staging.yaml openrig apply --config configs/prod.yaml或者用环境变量控制加载哪份# openrig.yaml provider: ${OPENRIG_ENV:-dev}配合 shell 里的export OPENRIG_ENVprod一条命令切换环境。这种模式在 CI/CD 里也好用流水线里根据分支设置不同的环境变量即可。6.3 与本地模型深度结合热词里“claude code 调用 lmstudio 的本地模型”代表了一类需求数据不出本地用本地推理。openrig 把本地模型的端点抽象成 provider 后切换成本极低。本地模型的坑在于性能和上下文长度。消费级显卡跑大模型上下文一长就爆显存响应也慢。我的经验是本地模型适合做代码补全、简单重构这类短上下文任务复杂推理还是交给云端。openrig 让你能按任务类型切换重活走云端轻活走本地成本和隐私兼顾。6.4 配置校验与自动化openrig 如果支持配置校验比如openrig validate务必在 CI 里跑一遍。YAML 写错了在本地可能只是某个功能不生效到了团队共享就是集体踩坑。加一道校验把语法错误、字段缺失、端点不可达这些问题挡在合并之前。再进一步可以写个脚本在apply后自动跑一次冒烟测试发一个最简单的请求给配置好的端点确认能拿到回复。这样每次改配置都有反馈不用等到真正干活时才发现问题。配置这东西平时不起眼出问题时最耗时间。openrig 这类工具的价值不在于它多复杂而在于它把散落的配置收拢成一份可读、可版本化、可切换的声明文件。我自己的习惯是每接一个新端点先在 YAML 里加一个 provider验证通过再挂到 agent 上一步一验证比一次性配一堆再排查要快得多。
