openrig：统一管理 Claude Code 与 Codex 的 AI 编码工具配置层

1. 从 openrig 说起一个被低估的 AI 编码工具配置层第一次看到openrig这个词我下意识把它拆成了 open rig——开放的装配台。这个直觉后来被验证是对的。它做的事情本质上是给当下最热的两个 AI 编码助手 Claude Code 和 Codex 提供一个统一、可版本化、可复用的配置装配层。如果你最近在折腾 Claude Code 或者 Codex大概率已经踩过这样的坑换一台机器要重新配一遍团队里每个人的配置各不相同YAML 文件散落在各个目录里找不到npm 全局包装了又卸、卸了又装PowerShell 还时不时甩你一个禁止运行脚本的红脸。openrig要解决的就是这些琐碎但极其消耗耐心的问题。它把 Claude Code、Codex 这类工具的配置抽象成结构化的 YAML 描述通过 npm 分发让你用一条命令就能把一整套编码助手的运行环境装配起来。适合谁来用三类人一是同时用 Claude Code 和 Codex 的开发者需要统一管理两套配置二是团队里负责搭基建的人需要把配置标准化后分发给成员三是喜欢折腾本地模型、想把 Claude Code 接到 LM Studio 或者把 Codex 接到 DeepSeek 的玩家。我写这篇东西的出发点很简单网上关于 Claude Code 安装、Codex 安装教程的内容已经很多了但几乎没人把配置管理这一层单独拎出来讲透。而openrig恰恰卡在这个位置上——它不是又一个 AI 编码工具而是管理这些工具的工具。这个定位决定了它的价值不在功能炫酷而在长期使用的稳定性和可维护性。2. 核心设计思路为什么是 YAML npm 这套组合2.1 配置即代码把散落的设置收进一个文件Claude Code 和 Codex 各自的配置方式不太一样。Claude Code 偏向在项目目录下放配置文件Codex 则更多依赖全局设置和命令行参数。当你同时用这两个工具再加上 VSCode 插件、终端环境变量、本地模型地址这些东西配置就会像藤蔓一样爬满整个系统。openrig的第一个设计决策就是把所有配置收敛到一个 YAML 文件里。为什么是 YAML 而不是 JSON 或者 TOML我个人的理解是三点。第一YAML 支持注释这对配置文件来说太重要了——你可以写清楚每个字段为什么这么设半年后回来看不至于一脸懵。第二YAML 的层级结构天然适合描述工具 → 环境 → 参数这种嵌套关系。第三Claude Code 和 Codex 生态里 YAML 出现频率极高从 CI 配置到模型参数大家已经习惯了学习成本几乎为零。提示YAML 对缩进极其敏感用空格不用 Tab。我见过太多人因为一个 Tab 导致整个配置解析失败排查半天。2.2 npm 作为分发通道的取舍用 npm 分发一个配置工具乍看有点奇怪但细想很合理。目标用户是开发者而开发者机器上几乎必然有 Node.js 和 npm。与其让你去下载一个二进制、配置 PATH、处理平台差异不如直接npm install -g一把梭。openrig选择 npm 还有一个隐性好处版本管理天然免费。你可以锁定某个版本团队里所有人装同一个版本配置行为就一致了。但 npm 也带来了一堆经典问题这些在热搜词里体现得淋漓尽致npm : 无法加载文件 ... npm.ps1因为在此系统上禁止运行脚本、npm 国内源、npm 镜像源地址、npm 卸载全局包、npm 环境变量 path 配置。这些不是 openrig 独有的问题而是所有走 npm 分发的工具都会遇到的通用坑。我在第 4 节会专门把这些坑一个个填掉。2.3 统一 Claude Code 与 Codex 的配置抽象这是openrig最有价值也最难的部分。Claude Code 和 Codex 虽然都是 AI 编码助手但配置模型差异不小。Claude Code 关注的是模型接入点、订阅权限、终端命令执行策略Codex 关注的是 endpoint、组织设置、登录态。openrig的做法是抽出一层中间表示——用统一的 YAML schema 描述我要接哪个模型、用哪个 endpoint、走什么认证然后在装配阶段翻译成各自工具认识的格式。这个抽象层的好处在于当你想把 Claude Code 从官方模型切到 LM Studio 的本地模型或者把 Codex 接到 DeepSeek你只需要改 YAML 里的一个字段而不是去翻两个工具各自的文档。坏处也很明显抽象层永远滞后于上游工具的变化一旦 Claude Code 或 Codex 改了配置格式openrig 就得跟着更新。所以用这类工具锁定版本、关注更新日志是必须的习惯。3. 环境准备把 npm 这匹野马先驯服3.1 Node.js 与 npm 的安装确认在碰openrig之前先把地基打牢。打开终端跑这两条node -v npm -v正常的话会输出类似v20.x.x和10.x.x。如果提示命令未找到说明 Node.js 没装或者没进 PATH。Windows 用户去 Node.js 官网下 LTS 版本安装时务必勾选Add to PATH。macOS 用户用brew install node最省事。Linux 用户建议用 nvm 管理版本避免系统包管理器装的版本太老。这里有个细节值得说Node.js 版本不要太新也不要太旧。太新比如某些奇数版本可能和 npm 包的兼容性有摩擦太旧16 以下很多现代包直接不支持。我实测下来Node 20 LTS 是目前最稳的选择Claude Code、Codex、openrig 这一圈工具都能跑得舒服。3.2 解决 PowerShell 禁止运行脚本的报错Windows 用户十有八九会撞上这个npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 npm 坏了是 PowerShell 的执行策略默认拦住了.ps1脚本。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后输入Y确认。RemoteSigned的意思是本地写的脚本可以跑从网上下载的脚本需要有签名。这个策略在安全性和可用性之间平衡得比较好比直接设成Unrestricted稳妥。改完之后关掉 PowerShell 重开再跑npm -v应该就正常了。注意如果你在公司电脑上操作执行策略可能被组策略锁死Set-ExecutionPolicy会报错。这种情况要么找 IT 开权限要么改用 CMD 或者 Git Bash 来跑 npm 命令绕开 PowerShell 的限制。3.3 配置国内镜像源加速安装npm 默认源在国外装包慢到让人怀疑人生。换成国内镜像源是标准操作npm config set registry https://registry.npmmirror.com设完之后用npm config get registry确认一下。想临时用一次别的源可以加--registry参数比如npm install openrig --registry https://registry.npmmirror.com。如果哪天想换回官方源npm config set registry https://registry.npmjs.org即可。这里插一句关于npm warn eresolve overriding peer dependency的说明。这个警告在装稍微复杂点的包时几乎必然出现它的意思是某个依赖要求的 peer 版本和实际装的不一致npm 帮你覆盖了。大多数情况下可以忽略但如果装完之后工具跑不起来就要认真看这个警告指向哪个包手动装对应版本。4. openrig 的安装与初始化实操4.1 全局安装与版本锁定装openrig本身很简单npm install -g openrig但我强烈建议加上版本号尤其是团队协作场景npm install -g openrig1.2.3为什么锁版本因为配置工具的行为一旦变化可能导致你昨天还能跑的 Claude Code 今天启动就报错。锁版本等于给团队一个确定的基线。升级的时候大家约好一起升出问题也好定位。装完之后验证openrig --version如果提示命令找不到八成是 npm 全局包的 bin 目录没进 PATH。用npm config get prefix看看全局前缀在哪然后把这个路径下的binLinux/macOS或者根目录Windows加进系统 PATH。这就是热搜里npm 环境变量 path 配置那个问题的根源。4.2 初始化配置文件openrig的初始化命令通常是openrig init它会在当前目录或者用户主目录下生成一个openrig.yaml模板。这个文件就是你的配置中枢。我建议把它放进项目的 Git 仓库敏感信息用环境变量引用这样团队每个人 clone 下来就能用同一套配置。一个典型的openrig.yaml结构大概长这样version: 1 tools: claude-code: enabled: true model: provider: anthropic endpoint: https://api.anthropic.com model_name: claude-sonnet-4 terminal: allow_exec: true timeout: 30 codex: enabled: true endpoint: https://api.openai.com/v1/responses auth: method: token token_env: CODEX_TOKEN字段含义我逐个说清楚。version是 schema 版本openrig 升级时靠它做兼容。tools下面是各个工具的配置块。claude-code里的model.provider决定走哪家模型endpoint是接入地址model_name是具体模型。terminal.allow_exec控制 Claude Code 能不能直接执行终端命令——这个开关很关键开了效率高但风险也高后面细说。codex的endpoint指向/responses接口auth.token_env表示从环境变量读 token避免把密钥写进文件。4.3 装配与生效配置写好后执行openrig apply这个命令会读取 YAML把配置翻译成 Claude Code 和 Codex 各自认识的格式写到它们该在的位置。执行完通常会提示你重启对应的工具或者终端。我一般会顺手跑一个openrig status看看每个工具的装配状态确认没有报错。提示openrig apply之前先备份一下原有的 Claude Code 和 Codex 配置。虽然 openrig 一般会做备份但自己留一手总没错尤其是你已经手动调过一些参数的情况下。5. 把 Claude Code 和 Codex 接上本地模型5.1 Claude Code 调用 LM Studio 本地模型这是很多人折腾 openrig 的核心诉求不想每次都走云端 API想在本地跑模型。LM Studio 提供了一个兼容 OpenAI 格式的本地服务默认地址是http://localhost:1234/v1。在openrig.yaml里把 Claude Code 的配置改成claude-code: enabled: true model: provider: openai-compatible endpoint: http://localhost:1234/v1 model_name: your-local-model api_key_env: LOCAL_API_KEY这里的关键是provider要设成openai-compatible因为 LM Studio 暴露的是 OpenAI 兼容接口。api_key_env指向一个环境变量本地模型通常不校验 key但有些客户端要求非空随便设个值就行。实测下来有几个坑要注意。第一LM Studio 要先在界面里把模型加载起来并且开启本地服务否则 endpoint 连不上。第二本地模型的上下文窗口往往比云端小Claude Code 处理大文件时容易截断建议在配置里限制单次读取的文件大小。第三本地推理速度取决于你的显卡7B 级别的模型在消费级显卡上勉强能用再大就明显卡顿。5.2 Codex 接入 DeepSeek 等第三方模型Codex 默认走 OpenAI 的/responses接口。想接 DeepSeek需要确认 DeepSeek 是否提供兼容的 endpoint。配置大概是这样codex: enabled: true endpoint: https://api.deepseek.com/v1/responses auth: method: token token_env: DEEPSEEK_API_KEY organization: disabled: true热搜里出现过codex无法加载组织设置和your organization has disabled claude subscription access这类问题基本都出在认证和组织配置上。接第三方模型时把organization.disabled设成true避免 Codex 去请求一个不存在的组织信息。token 通过环境变量注入别硬编码。5.3 处理 endpoint 代理失败的报错热搜里有一条很典型的报错cc switch local proxy failed while handling codex endpoint /responses。这个错误的本质是Claude Code 和 Codex 在切换配置时本地代理层没能正确转发到/responses这个路径。排查思路分三步。第一确认 endpoint 地址拼写正确/responses不能少也不能多斜杠。第二确认本地代理端口没被占用换个端口试试。第三看 openrig 的日志openrig status --verbose会打印详细的请求路径一眼就能看出转发到哪去了。我踩过一次这个坑最后发现是 YAML 里 endpoint 写成了https://api.deepseek.com/v1/responses/末尾多了个斜杠代理转发时路径就错了。这种细节不看日志真的很难发现。6. 常见问题速查与避坑经验6.1 npm 相关高频问题对照表报错/现象根本原因解决办法npm.ps1 禁止运行脚本PowerShell 执行策略限制Set-ExecutionPolicy RemoteSigned -Scope CurrentUser安装极慢或超时默认源在国外换国内镜像源registry.npmmirror.comopenrig 命令找不到全局 bin 目录未进 PATH把npm config get prefix对应路径加入 PATHeresolve overriding peer dependency依赖版本冲突多数可忽略工具异常时手动装指定版本卸载不干净全局包残留npm uninstall -g openrig后手动清理缓存6.2 YAML 配置的常见书写错误YAML 看着简单坑却不少。缩进用 Tab 是最常见的致命错误解析器直接报错。冒号后面必须跟空格key:value是错的key: value才对。字符串里有特殊字符比如:、#要加引号。多行字符串用|或前者保留换行后者折叠换行。我建议写完 YAML 后用在线校验器过一遍或者用openrig validate命令检查能省下大量排查时间。6.3 权限与安全相关的注意事项claude-code.terminal.allow_exec这个开关我单独拎出来说。打开它Claude Code 就能直接在你的终端执行命令效率确实高但它意味着 AI 生成的命令会真实地在你机器上跑。我的做法是个人开发机可以开但配合timeout限制单条命令执行时间生产环境或者存有敏感数据的机器坚决不开。同理Codex 的 token 一定要走环境变量别写进 YAML 提交到仓库这是底线。6.4 版本升级与回滚策略openrig、Claude Code、Codex 这三个东西都在快速迭代版本组合不对就容易出问题。我的经验是维护一个已知可用的版本组合写进团队文档。升级时先在小范围试确认没问题再推给所有人。回滚很简单npm install -g openrig旧版本号就行但记得同时回滚 YAML 配置因为新版本可能引入了旧版本不认识的字段。7. 我个人的一些实操体会折腾 openrig 这一圈下来最大的感受是AI 编码工具本身的能力固然重要但真正决定日常体验的往往是配置管理这一层。一个配置混乱的环境再强的模型也救不了你的效率。openrig 的价值不在于它多聪明而在于它把配置这件事从手工活变成了可版本化、可复现的工程实践。如果你刚开始接触我的建议是从最小配置起步先只配 Claude Code跑通之后再加 Codex最后再考虑接本地模型。一次性把所有东西都配上出问题时你根本不知道是哪一层坏了。另外把openrig.yaml纳入 Git 管理每次改动都提交这样任何一次配置变更都有迹可循回滚也就是一条git revert的事。最后分享一个小技巧openrig 的配置里可以给每个工具加一个notes字段写点只有你自己看得懂的备注比如这个 endpoint 是测试环境的别用于正式任务。这种看似无用的注释在几个月后你回头看配置时能救命。