1. openrig 到底是个什么东西第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者机械臂项目毕竟 rig 这个词在工程领域通常指“装配、支架、机架”。但结合 claude code、codex、yaml、node.js 这几个热搜词一起看方向就很清楚了这是一个围绕 AI 编程助手做本地配置编排的工具核心工作是把 Claude Code、Codex 这类命令行 AI 编码代理的接入参数、模型端点、代理转发规则统一用 YAML 描述出来再由 Node.js 运行时去加载和执行。说白了openrig 解决的是一个很具体的痛点。现在用 AI 编程助手的人越来越多但每个人手里的模型来源五花八门有人用官方订阅有人接第三方兼容端点有人本地跑 LM Studio 或者 Ollama还有人要在 DeepSeek、Qwen、GLM 之间来回切换。每换一次模型就要改一次环境变量、改一次配置文件、重启一次终端时间全耗在配置上了。openrig 的思路就是把这些零散的配置收敛到一个 YAML 文件里用一套结构化的 schema 管理多个 provider、多个模型、多个 profile切换的时候只改一行引用就行。它适合谁三类人最需要。第一类是同时用 Claude Code 和 Codex 的开发者两边配置格式不一样来回切换很烦第二类是在公司内网或者受限网络环境下工作的人需要把请求指向自建网关或者本地模型服务第三类是喜欢折腾、想把 AI 编码工具链做成可版本化管理的人配置进 Git换电脑一键还原。如果你只是偶尔用一下网页版对话那 openrig 对你意义不大但如果你每天有大量时间泡在终端里让 AI 帮你写代码、改 bug、跑测试那这套东西值得花半小时搭起来。需要先说明一点openrig 目前并不是一个官方统一发布的标准工具社区里存在多个同名或近似的实现有的叫 openrig有的叫 cc-rig、codex-rig。它们的设计思路高度相似都是“YAML 描述 Node.js 执行 多 provider 适配”。下面我讲的这套方案是基于这类工具最常见的实践形态来展开的具体字段名可能和你手上的版本有出入但核心逻辑是通用的。2. 整体设计思路与方案选型2.1 为什么用 YAML 而不是 JSON 或 TOML配置格式的选择看着是小事实际影响很大。JSON 的问题是没法写注释你过两个月回来看base_url: http://127.0.0.1:1234/v1这行根本想不起来这个端口对应的是哪个本地服务。TOML 表达嵌套结构比较别扭尤其是当你要描述“多个 provider每个 provider 下有多个 model每个 model 又有自己的参数覆盖”这种三层结构时TOML 的[provider.model.param]写法会变得很长很啰嗦。YAML 的优势在于三点。第一是支持注释这对配置文件来说是刚需你可以在每个 provider 旁边写清楚“这是公司网关仅内网可用”“这是本地 LM Studio需要先启动服务”。第二是缩进表达层级三层嵌套读起来依然清晰。第三是它对多行字符串友好写系统提示词、写自定义 header 的时候不用转义换行符。当然 YAML 也有坑最大的坑就是缩进必须用空格不能用 Tab而且缩进层级错了不会报错只会静默解析成别的结构。这个后面排查章节会详细讲。2.2 为什么用 Node.js 做运行时Claude Code 和 Codex 本身都是 Node.js 生态里的 CLI 工具通过 npm 全局安装。openrig 选择 Node.js 作为运行时最大的好处是零额外依赖——你机器上为了跑 AI 助手本来就已经装了 Node不需要再装 Python 或者 Go。其次 Node.js 的child_process模块可以很方便地 spawn 子进程把配置注入环境变量后启动 claude 或 codex 命令进程管理很自然。另外一个考虑是跨平台。Node.js 在 Windows、macOS、Linux 上的行为基本一致路径处理用path模块、环境变量用process.env写一套逻辑三个平台都能跑。相比之下如果用 shell 脚本写Windows 上就得再维护一套 PowerShell 版本维护成本翻倍。2.3 多 provider 抽象层的设计openrig 最核心的设计是 provider 抽象。不管你是官方端点、第三方兼容服务、本地模型在配置里都统一成一个 provider 对象包含base_url、api_key、model这几个必备字段再加上可选的headers、timeout、max_tokens等覆盖项。这样做的好处是Claude Code 和 Codex 虽然底层协议不同一个走 Anthropic 的 messages 格式一个走 OpenAI 的 responses 格式但在 openrig 这一层可以统一描述。启动的时候openrig 根据目标工具类型把统一的 provider 配置翻译成对应工具认识的环境变量。比如给 Claude Code 就设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY给 Codex 就设置OPENAI_BASE_URL和OPENAI_API_KEY。这个翻译层是整个工具的价值所在。没有它你就得记住两套完全不同的环境变量命名规则还得记住哪些工具读哪个变量。有了它你只关心“我要用哪个 provider”剩下的映射交给 openrig。2.4 profile 机制解决切换问题provider 解决了“连哪里”的问题profile 解决的是“用哪套组合”的问题。一个 profile 可以理解为一份预设用哪个 provider、用哪个模型、带哪些额外参数、注入哪些环境变量。举个实际场景。我白天在公司用内网网关晚上回家用本地 LM Studio周末偶尔切到第三方兼容服务测新模型。这三个场景就是三个 profilework、local、cloud。切换的时候只需要openrig use local然后正常启动 claude 或 codex 就行不用手动改任何环境变量。profile 还支持继承。比如work-fast和work-quality都继承自work只是覆盖了 model 字段。这样公共配置只写一份差异部分单独声明维护起来清爽很多。3. 核心配置细节与实操要点3.1 目录结构与文件布局openrig 的配置默认放在用户主目录下的.openrig文件夹里结构大概是这样~/.openrig/ ├── config.yaml # 主配置定义 provider 和 profile ├── profiles/ # 可选profile 拆分文件 │ ├── work.yaml │ └── local.yaml └── logs/ # 运行日志 └── openrig.log主配置和拆分文件的关系是主配置里可以用include引入 profiles 目录下的文件也可以全部写在一个 config.yaml 里。我个人的习惯是 provider 定义写在主配置因为 provider 数量相对固定profile 按场景拆成独立文件因为场景会经常增删。提示.openrig目录建议加入版本控制但logs目录要加进.gitignore。config.yaml 里如果写了 api_key要么用环境变量引用要么确保仓库是私有的。3.2 provider 字段详解一个典型的 provider 定义长这样providers: local-lmstudio: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: ${LMSTUDIO_KEY:-not-needed} model: qwen2.5-coder-7b-instruct timeout: 120000 headers: X-Custom-Header: openrig逐字段说明。type决定协议适配器常见值有anthropic、openai-compatible、openai-responses。base_url是端点根地址注意本地服务通常要带/v1后缀而有些网关不带这个要看你实际服务的文档。api_key支持${VAR}语法引用环境变量:-后面是默认值本地服务不需要鉴权的时候写not-needed占位就行。model是默认模型名profile 里可以覆盖。timeout单位是毫秒本地小模型推理慢建议给到 120000 也就是两分钟云端服务 30000 就够了。headers是自定义请求头有些网关需要额外的鉴权头或者路由头在这里加。注意base_url结尾不要多加斜杠。http://127.0.0.1:1234/v1和http://127.0.0.1:1234/v1/在部分实现里会被拼成//v1//chat/completions导致 404。这个坑我踩过不止一次。3.3 profile 字段详解profile 定义示例profiles: local: provider: local-lmstudio model: qwen2.5-coder-7b-instruct env: OPENRIG_PROFILE: local args: - --max-tokens - 8192 work: provider: company-gateway model: gpt-5.6-sol env: NO_PROXY: 127.0.0.1,localhostprovider字段引用上面定义的 provider 名。model覆盖 provider 的默认模型。env是额外注入的环境变量比如有些工具需要NO_PROXY来跳过本地地址。args是透传给 CLI 的额外参数注意这里要用字符串形式数字也要加引号否则 YAML 会解析成数字类型某些 CLI 会报参数类型错误。profile 继承写法profiles: work: provider: company-gateway model: gpt-5.6-sol work-fast: extends: work model: gpt-5.6-sol-miniextends指向父 profile子 profile 只需声明差异字段。解析的时候 openrig 会做深合并env和headers这类字典是合并而不是替换这点设计得比较合理。3.4 环境变量注入的时机这是整个流程里最容易出问题的地方。openrig 注入环境变量的时机是在 spawn 子进程之前通过child_process.spawn的env选项传入。这意味着两件事。第一注入的环境变量只对 openrig 启动的那个子进程生效不会污染你当前 shell 的环境。你在这个终端里手动敲echo $ANTHROPIC_BASE_URL是看不到的这是正常的不要以为没生效。第二如果 Claude Code 或 Codex 内部又 spawn 了子进程比如调用 git、调用测试命令这些孙进程会继承环境变量。所以如果你在 profile 里设置了NO_PROXY它会影响 AI 助手执行的所有命令这个要心里有数。实操心得想验证环境变量到底注入了没有可以在 profile 的 args 里临时加一个打印环境变量的命令或者直接看 openrig 的 debug 日志。日志里会记录实际 spawn 的完整命令和环境变量快照排查问题全靠它。4. 完整实操流程与关键环节4.1 环境准备Node.js 安装与版本选择openrig 要求 Node.js 18 以上推荐 20 LTS 或 22 LTS。安装方式按平台分。Windows 用户直接去 Node.js 官网下载 LTS 版本的 msi 安装包一路下一步就行。安装完打开 PowerShell 敲node -v能输出版本号就成功了。注意不要用太新的奇数版本比如 23.x有些原生模块还没适配容易出NODE_MODULE_VERSION不匹配的报错。macOS 用户推荐用 nvm 管理版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc nvm install 20 nvm use 20Ubuntu 用户同样推荐 nvm不要用apt install nodejs系统源里的版本通常太老。如果遇到error installing 24.21.0: node.js v24.21.0 is not yet released这类报错说明你指定的版本号不存在去 Node.js 官网确认一下当前 LTS 的实际版本号。装完 Node 之后npm 会一起装上。国内网络环境下建议配一下镜像源加速npm config set registry https://registry.npmmirror.com4.2 安装 Claude Code 和 Codex两个工具都是 npm 全局包npm install -g anthropic-ai/claude-code npm install -g openai/codex安装完分别敲claude --version和codex --version验证。如果提示命令找不到检查 npm 全局 bin 目录有没有加到 PATH 里。用 nvm 的话一般自动配好了用系统包管理器装的可能要手动加。注意Claude Code 和 Codex 的包名会随版本更新变化如果上面命令报 404去官方文档确认最新的包名。安装过程中如果卡在 postinstall 脚本多半是网络问题配好镜像源重试。4.3 安装 openrig 本体假设 openrig 以 npm 包形式分发npm install -g openrig openrig initopenrig init会在~/.openrig下生成一份带注释的示例配置里面预置了几个常见 provider 模板。第一次跑的时候它会检测你机器上装了哪些 AI 助手自动生成对应的 profile 骨架。如果 openrig 是以源码形式分发的流程是git clone repo-url openrig cd openrig npm install npm linknpm link会把当前目录链接到全局 bin这样你就能在任何地方敲openrig命令了。开发模式下改代码不用重新安装改完直接生效。4.4 配置第一个 provider打开~/.openrig/config.yaml先配一个本地 LM Studio 的 provider 做测试因为本地服务不依赖外部网络排查问题最简单。providers: local-lmstudio: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed model: qwen2.5-coder-7b-instruct timeout: 120000启动 LM Studio加载一个模型确认服务在 1234 端口监听。然后配 profileprofiles: local: provider: local-lmstudio保存后执行openrig use local openrig doctoropenrig doctor是自检命令它会依次检查配置文件语法、provider 连通性、目标 CLI 是否安装、环境变量映射是否正确。这一步能过基本就成功了一大半。4.5 启动与验证自检通过后用 openrig 启动 Claude Codeopenrig run claude或者启动 Codexopenrig run codexopenrig 会读取当前激活的 profile翻译成对应工具的环境变量然后 spawn 子进程。你看到的界面和直接敲claude是一样的但底层已经连到你配置的 provider 了。验证是否真的走了自定义端点最简单的办法是看 LM Studio 的日志窗口有没有收到请求。如果 LM Studio 那边有请求进来说明链路通了。如果 Claude Code 报错说连不上先看 openrig 的 debug 日志里面会打印实际使用的 base_url。4.6 多 provider 切换实战配好本地之后再加一个云端 providerproviders: cloud-gateway: type: openai-compatible base_url: https://your-gateway.example.com/v1 api_key: ${CLOUD_API_KEY} model: gpt-5.6-sol timeout: 60000 profiles: cloud: provider: cloud-gateway cloud-fast: extends: cloud model: gpt-5.6-sol-miniCLOUD_API_KEY通过环境变量传入不要硬编码在配置文件里。在 shell 的 rc 文件里加一行export CLOUD_API_KEYxxx或者用系统的密钥管理工具。切换的时候openrig use cloud openrig run claude想切回来openrig use local openrig run claudeopenrig use会把当前 profile 名写到一个状态文件里下次openrig run自动读取。也可以用openrig run --profile cloud claude临时指定不改变全局状态。5. 常见问题与排查技巧实录5.1 YAML 解析类问题YAML 最坑的地方是缩进错误不报错。比如你把model字段多缩进了一级它可能被解析成上一个字段的子属性而不是报语法错误。表现就是配置看起来没问题但启动后模型名是空的。排查方法用openrig config show打印解析后的最终配置对比你写的 YAML看结构对不对。或者用在线 YAML 校验工具先过一遍。另一个常见问题是特殊字符。api_key里如果有:或者#必须加引号否则会被当成键值分隔符或者注释起始符。稳妥做法是所有字符串值都加双引号。5.2 连接类问题速查表现象可能原因排查动作连接被拒绝本地服务没启动检查 LM Studio 是否在运行端口是否一致404 Not Foundbase_url 路径错误确认是否要带 /v1结尾不要多斜杠401 Unauthorizedapi_key 未注入检查环境变量是否 export${VAR}语法是否正确超时timeout 太短或模型太慢本地模型调到 120000云端 30000模型不存在model 名拼写错误用服务端的模型列表接口确认准确名称请求发到了官方端点环境变量没生效看 openrig debug 日志里的 env 快照5.3 Claude Code 特有的坑Claude Code 对ANTHROPIC_BASE_URL的处理有个细节它会在 base_url 后面自动拼/v1/messages。所以你的 base_url 应该写到域名或者网关根路径不要自己带/v1。这点和 Codex 不一样Codex 是拼/v1/responsesbase_url 通常要带/v1。openrig 的适配层会根据工具类型自动处理这个差异但如果你手动改环境变量一定要记住这个区别。还有一个报错your organization has disabled claude subscription access for claude code这个和 openrig 无关是账号层面的订阅权限问题需要去账号设置里确认订阅状态。5.4 Codex 特有的坑Codex 报the gpt-5.6-sol model is not supported when using codex with a...这类错误通常是模型名和 Codex 的协议不匹配。Codex 走的是 responses 格式不是所有兼容 OpenAI 的服务都实现了这个格式。遇到这种情况要么换一个支持 responses 格式的 provider要么在 openrig 里把 type 改成openai-compatible让它走 chat completions 格式做转换。Codex 还有个无法加载组织设置的报错一般是登录态问题。先codex logout再codex login重新走一遍认证流程。5.5 环境变量污染问题前面提过openrig 注入的环境变量会被 AI 助手 spawn 的所有子进程继承。如果你在 profile 里设置了HTTP_PROXY之类的变量AI 助手执行npm install的时候也会走这个代理可能导致内网包拉不下来。解决办法是在 profile 的 env 里显式设置NO_PROXY把本地地址和内网域名排除掉env: NO_PROXY: 127.0.0.1,localhost,.internal.example.com实操心得我习惯给每个 profile 都加一个OPENRIG_PROFILE环境变量值就是 profile 名。这样在 AI 助手执行的脚本里可以通过这个变量判断当前处于哪个环境做一些条件逻辑。这个技巧在写自动化脚本的时候特别有用。5.6 日志与调试openrig 的日志默认在~/.openrig/logs/openrig.log。想看实时日志tail -f ~/.openrig/logs/openrig.log日志级别可以在配置里调log_level: debugdebug 级别会打印完整的 spawn 命令、环境变量快照、provider 解析结果。排查问题的时候先开 debug问题定位了再调回 info不然日志文件涨得很快。如果日志里看不到有用信息可以在启动命令前加DEBUGopenrig:*DEBUGopenrig:* openrig run claude这会把调试信息直接打到终端比翻日志文件快。6. 进阶玩法与扩展思路6.1 配置进 Git 做版本管理把~/.openrig/config.yaml和profiles/目录纳入 Git 管理换电脑的时候 clone 下来就能用。api_key 这类敏感信息用环境变量引用不写进文件。可以建一个config.example.yaml作为模板提交实际的config.yaml加进.gitignore。团队协作的时候可以把公共的 provider 定义放在一个共享仓库里每个人用自己的 profile 覆盖个人偏好。openrig 的include机制支持从多个路径加载配置合并顺序按声明顺序来后面的覆盖前面的。6.2 结合本地模型做离线开发本地跑 LM Studio 或者 Ollama 的最大好处是断网也能用而且数据不出本机。对于处理敏感代码的场景这个价值很大。openrig 的 provider 抽象让本地模型和云端模型在使用体验上完全一致切换只需要改一行 profile 引用。本地模型的选型上代码场景推荐 Qwen2.5-Coder 系列或者 DeepSeek-Coder 系列7B 起步有条件上 14B 或 32B。显存不够的话用 4bit 量化版本质量损失在可接受范围内。6.3 多模型并行对比openrig 支持同时配多个 provider你可以开两个终端一个跑openrig run --profile local claude另一个跑openrig run --profile cloud claude同一个问题分别问本地模型和云端模型对比输出质量。这个用法在评估“本地模型够不够用”的时候特别直观。6.4 自动化脚本集成openrig 的命令行接口设计得比较适合脚本调用。比如你想在 CI 里跑 AI 代码审查可以这样写openrig use ci-profile openrig run claude -- --print review the diff in this PR review.txt--后面的参数会透传给 Claude Code。这样就能把 AI 审查集成到流水线里每次 PR 自动跑一遍。注意CI 环境里没有交互式终端Claude Code 和 Codex 的某些功能可能受限。建议在 CI 里只用非交互模式并且设置合理的超时避免流水线卡死。6.5 配置校验与 schemaopenrig 支持 JSON Schema 校验配置文件。在 config.yaml 顶部加一行# yaml-language-server: $schemahttps://example.com/openrig-schema.json这样在 VS Code 里编辑的时候会有自动补全和错误提示能提前发现字段名拼写错误、类型不匹配等问题。schema 文件地址以你实际使用的 openrig 版本为准。7. 我踩过的几个坑和对应解法第一个坑是 YAML 的 Tab 缩进。我用 VS Code 编辑的时候有时候不小心按了 Tab文件看起来对齐了但解析出来结构全乱。后来在 VS Code 设置里把editor.insertSpaces设为 trueeditor.tabSize设为 2并且打开renderWhitespace让空格和 Tab 可视化这个问题就再没出现过。第二个坑是环境变量默认值的语法。${VAR:-default}这个写法在 shell 里很常见但 openrig 的解析器不一定完全兼容。我遇到过:-后面的默认值带空格导致解析失败的情况。稳妥做法是默认值不要带空格或者干脆不用默认值确保变量一定被设置。第三个坑是 profile 继承的合并顺序。我一开始以为子 profile 的env会完全替换父 profile 的env结果发现是深合并。这导致我父 profile 里设的一个环境变量一直生效覆盖不掉。后来改成在子 profile 里把那个变量显式设为空字符串才解决。用继承的时候一定要清楚合并规则。第四个坑是本地模型的超时。我一开始按云端习惯设了 30 秒结果本地 7B 模型处理长上下文的时候经常超时。后来统一改成 120 秒并且把max_tokens调小到 4096稳定性好了很多。本地模型的能力边界要心里有数不要指望它处理超长文件。第五个坑是端口冲突。LM Studio 默认 1234Ollama 默认 11434有时候两个都开着配置里写错了端口请求发到了另一个服务上返回的模型列表对不上排查了半天。现在我的习惯是每个本地服务用固定端口并且在 provider 的注释里写清楚端口对应哪个服务。这套东西搭起来之后我每天的工作流变成了早上到公司openrig use work晚上回家openrig use local周末测新模型openrig use cloud。配置全部在 Git 里换电脑五分钟还原。如果你也在多个模型和多个工具之间来回切换花点时间把 openrig 配起来长期看省下的时间很可观。