1. 从 openrig 这个标题说起它到底想解决什么问题第一次看到 openrig 这个名字我脑子里蹦出来的第一反应是“开放的工具台”。rig 在英文里有“装配、搭台子”的意思open 则点明了它的定位——开放、可插拔、不绑定某一家模型服务。把这两个词拼在一起再结合热搜里那一长串 Claude Code、Codex、YAML、Node.js 的关键词基本能判断出 openrig 想做的事情给当下这些命令行 AI 编程助手搭一个统一的、可自由配置的“底座”让你不用被某一家官方订阅、某一种登录方式、某一个模型供应商锁死。我自己是从 Claude Code 刚火起来那阵子开始折腾这类工具的。当时最头疼的不是模型能力而是配置。Claude Code 要装 Node.jsCodex 要装它自己的 CLI两个工具各有各的配置文件、各有各的环境变量、各有各的登录态。你想让它们都指向本地跑的模型或者指向某个第三方兼容接口就得分别去改改完还容易互相打架。openrig 这类项目出现的背景就是这种“工具碎片化”的痛点。所以这篇东西我打算按一个真实折腾者的视角来写openrig 是什么、它背后的核心思路、YAML 配置怎么写、Node.js 环境怎么搭、Claude Code 和 Codex 怎么接进来、本地模型和第三方接口怎么配、踩过的坑怎么排。适合谁看适合那些已经装了 Claude Code 或 Codex、但被配置折磨过的人也适合刚听说这些工具、想一次性把环境搭明白的新手。我会尽量把每一步的理由讲清楚而不是只丢一堆命令让你抄。需要先说明一点openrig 本身是一个相对新的项目网上公开的完整文档还不算多很多细节我是基于这类“统一配置层”工具的常见设计模式来推演和补全的。凡是推演的部分我都会点明你实际用的时候以项目仓库的最新说明为准。2. openrig 的核心设计思路拆解2.1 为什么需要一层“中间配置”要理解 openrig 的价值得先理解现在这些 AI 编程 CLI 工具的配置有多乱。Claude Code 的配置通常放在用户目录下的隐藏文件夹里Codex 有它自己的一套第三方工具比如各种模型切换器又是另一套。每换一个模型供应商你就要动一次配置每换一台机器你就要重新配一遍。这种重复劳动在只用一个工具时还能忍一旦你同时用 Claude Code 和 Codex甚至还要在它们之间切换不同的模型后端配置就变成了一团乱麻。openrig 的思路很像前端工程里的“统一构建配置”。它不直接替代 Claude Code 或 Codex而是在它们和你实际使用的模型服务之间插一层统一的配置和转发层。你用一份 YAML 描述清楚“我要用哪个模型、走哪个接口、用什么密钥、映射到哪个工具”openrig 负责把这套描述翻译成各个工具能认的格式。这样你改一处所有接进来的工具都跟着变。这个设计的好处很直接配置集中、切换成本低、可版本化管理。你把 YAML 丢进 Git换机器时 clone 下来就能复现整套环境。坏处也有多了一层出问题时排查链路变长你得先确认是 openrig 这层的问题还是下游工具的问题。这一点后面排查章节会细讲。2.2 YAML 作为配置语言的选择逻辑热搜里“yaml 文件”“yolov10 yaml 文件怎么创建”“rstudio 的 yaml 在哪里”这些词混在一起说明很多人对 YAML 本身就不熟。openrig 选 YAML 而不是 JSON 或 TOML我认为有几个现实理由。YAML 的可读性比 JSON 好没有那么多括号和引号写配置时不容易因为少个逗号就整个文件报错。它支持注释这对配置文件的维护极其重要——你可以在某个模型配置旁边写一句“这个是给本地测试用的”半年后回来看还能想起来。YAML 还支持锚点和引用多个工具共用同一段模型配置时可以定义一次、引用多次避免复制粘贴导致的改一处漏一处。但 YAML 的坑也很经典缩进必须用空格不能用 Tab层级靠缩进表达缩进错了含义就完全变了。我见过太多人因为编辑器自动把 Tab 转成空格、或者混用了两种缩进导致配置读出来是空的。所以写 openrig 配置时第一件事就是把编辑器设成“Tab 转 2 空格”或“Tab 转 4 空格”并且全程统一。2.3 Node.js 在整个链路里的角色热搜里“node.js”“node.js 安装”“node.js 是干什么的”“node.js lts 下载”出现频率极高这不是偶然。Claude Code 和 Codex 的 CLI 基本都是 Node.js 生态的产物通过 npm 全局安装。openrig 如果也是 Node.js 写的那它同样依赖 Node 运行时。Node.js 在这里的角色就是“运行环境”。你可以把它理解成 Java 的 JVM——没有它那些用 JavaScript/TypeScript 写的命令行工具就跑不起来。所以整条链路是先装 Node.js再用 npm 装 Claude Code、Codex、openrig然后 openrig 读取 YAML把配置分发给各个工具。版本选择上我强烈建议用 LTS 版本。热搜里有一条“error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava”这就是典型的版本踩坑——装了一个还没正式发布或者已经下架的版本号npm 直接报错。LTS 版本经过长期验证兼容性最好别去追最新的奇数版本。3. 环境搭建从零把 Node.js 和工具链装明白3.1 Node.js 安装的正确姿势Windows 用户直接去 Node.js 官网下载 LTS 的安装包一路下一步就行。安装时有个选项叫“Add to PATH”一定要勾上否则命令行里敲 node 会提示找不到命令。装完打开新的终端敲node -v和npm -v能打印出版本号就说明成了。macOS 用户我建议用包管理器装比手动下载省心。如果你装了 Homebrew直接brew install node20这类命令即可。用 nvm 管理多版本会更灵活尤其是你同时要维护几个不同 Node 版本的项目时。Ubuntu 用户注意系统自带的 apt 源里的 Node 版本往往很旧直接apt install nodejs可能装到十几年前的版本。正确做法是先加 NodeSource 的源或者用 nvm 装。nvm 的好处是不需要 sudo装出来的 Node 在用户目录下权限干净。# 用 nvm 安装 LTS 版本macOS / Ubuntu 通用 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置后 nvm install --lts nvm use --lts node -v装完之后验证 npm 的全局目录是否在 PATH 里。有时候 npm 全局装的命令敲不出来就是因为全局 bin 目录没进 PATH。用npm config get prefix看一下路径再确认这个路径下的 bin 目录在 PATH 里。3.2 Claude Code 与 Codex 的安装顺序这两个工具的安装本身不复杂难的是装完之后怎么让它们和 openrig 协同。我的建议是先单独把每个工具装好、能独立跑起来再引入 openrig 做统一管理。这样出问题时你能快速判断是工具本身没装好还是 openrig 配置的问题。Claude Code 一般通过 npm 全局安装装完在终端敲它的命令第一次会引导你登录或配置。Codex 同理有它自己的安装包和 CLI。热搜里“codex 安装包”“codex 安装 windows 桌面版”“codex cli”说明它的安装形态不止一种有 CLI 也有桌面版你要根据自己需求选。如果只是想接进 openrig 做统一配置CLI 版本更合适因为桌面版往往有自己的图形化配置和外部配置层配合起来反而别扭。安装顺序上我习惯 Node.js → Claude Code → Codex → openrig。每装完一个就验证一次别一口气全装完再一起调那样出问题你根本不知道是哪一步坏的。3.3 openrig 的获取与初始化openrig 的获取方式通常是 clone 仓库或者通过包管理器安装。clone 的好处是你能直接看到它的示例配置和文档改起来方便。初始化时一般会生成一份默认的 YAML 配置模板你要做的就是在这个模板基础上填自己的模型信息。初始化完成后先别急着接真实模型用它的“自检”或“dry-run”模式跑一遍确认它能正确解析 YAML、能找到下游工具的路径。很多问题在这一步就能暴露比如 YAML 缩进错误、工具路径没配对、环境变量缺失。提示初始化生成的配置文件先备份一份。后面改乱了可以直接回滚比重装省事得多。4. YAML 配置实战把模型和工具接起来4.1 一份最小可用的 openrig 配置长什么样下面这份配置是我根据这类工具常见结构推演出来的示例字段名你以实际项目为准但结构逻辑是通用的# openrig 主配置 version: 1 # 模型供应商定义 providers: local-lmstudio: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder-7b - deepseek-coder-v2 remote-thirdparty: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${THIRDPARTY_API_KEY} models: - deepseek-chat - glm-4 # 工具绑定哪个工具用哪个 provider tools: claude-code: provider: local-lmstudio model: qwen2.5-coder-7b codex: provider: remote-thirdparty model: deepseek-chat这份配置里providers段定义“有哪些模型服务可用”tools段定义“哪个工具用哪个服务”。${THIRDPARTY_API_KEY}是环境变量引用密钥不写死在文件里这样你把配置提交到 Git 也不会泄露密钥。4.2 本地模型接入以 LM Studio 为例热搜里“claude code 调用 lmstudio 的本地模型”是个高频需求。LM Studio 启动本地服务后默认会在127.0.0.1:1234提供一个兼容 OpenAI 格式的接口。openrig 里只要把base_url指向这个地址api_key随便填一个非空值本地服务通常不校验就能把 Claude Code 或 Codex 的请求导到本地模型上。这里有个关键点本地模型的上下文窗口往往比云端小。Claude Code 这类工具在干活时会塞进去大量文件内容如果你的本地模型只支持 8K 上下文很容易爆。所以选本地模型时优先挑支持 32K 以上上下文的比如各种 coder 专用模型。另外本地推理速度取决于你的显卡7B 模型在消费级显卡上还能接受再大就明显卡了。4.3 第三方接口接入的注意事项接第三方接口时最容易出问题的是接口格式兼容性。很多第三方服务号称“兼容 OpenAI 格式”但细节上有差异比如流式返回的字段名、错误码的结构、function calling 的支持程度。openrig 如果做了格式转换能抹平一部分差异但抹不平全部。我的经验是先用 curl 直接打第三方接口确认基础对话能通再把它接进 openrig。这样能把“接口本身不通”和“openrig 配置不对”两个问题分开。热搜里“codex 接入 deepseek”“使用 cc switch 接入 deepseek v4, qwen, glm 等模型”都是这个场景思路一致。密钥管理上永远用环境变量不要写进 YAML。如果你在团队里共享配置把密钥放在每个人的本地环境变量里YAML 只引用变量名。4.4 YAML 缩进与常见语法坑YAML 的坑我踩过太多次这里集中列一下坑点表现正确做法用 Tab 缩进解析报错或层级错乱全程用空格统一 2 或 4 个冒号后没空格值被当成键的一部分key: value冒号后必须有空格字符串含特殊字符没引号解析异常含:、#、{的值加引号布尔值歧义yes/no/on/off被转成布尔需要字符串时加引号多行字符串缩进错内容被截断用 写完 YAML 后找个在线 YAML 校验器或者用python -c import yaml; yaml.safe_load(open(config.yaml))验证一下能省掉大量“配置看起来对但就是不通”的时间。5. 实操全流程从装好到跑通5.1 完整操作步骤清单把前面的内容串成一条可执行的流水线按顺序来安装 Node.js LTS验证node -v和npm -v。全局安装 Claude Code独立跑通一次。全局安装 Codex CLI独立跑通一次。获取 openrig初始化配置模板。编辑 YAML先只配一个 provider建议先用本地模型不依赖网络。用 openrig 的自检模式验证配置解析。启动 openrig让它接管工具请求。在 Claude Code 里发一条简单指令观察请求是否走到预期模型。确认无误后再增加第二个 provider 和第二个工具绑定。把配置提交到 Git密钥留在本地环境变量。这个顺序的核心逻辑是“一次只引入一个变量”。每加一个东西就验证一次出问题时变量少好定位。5.2 参数选择与计算过程选模型时有两个参数要算清楚上下文窗口和显存占用。上下文窗口决定你一次能塞多少代码进去显存占用决定你能不能跑得动。显存占用的粗略估算模型参数量乘以每个参数的字节数再加上 KV cache。以 7B 模型、FP16 精度为例权重约 14GBKV cache 取决于上下文长度和批大小。如果你显卡只有 8GB那 7B FP16 就跑不动得用量化版本比如 4-bit 量化后权重降到约 4GB就能塞进 8GB 显存。上下文窗口方面Claude Code 干活时经常需要读多个文件我建议至少 32K。如果你的本地模型只有 8K那就别用它接 Claude Code接一些简单的问答场景还行。5.3 实操现场记录一次完整的接入我拿本地 LM Studio 接 Claude Code 走一遍。先在 LM Studio 里加载一个 coder 模型启动本地服务确认http://127.0.0.1:1234/v1/models能返回模型列表。然后在 openrig 的 YAML 里把 claude-code 的 provider 指向 local-lmstudiomodel 填 LM Studio 里加载的那个模型名。启动 openrig再开一个终端跑 Claude Code。发一句“帮我看看当前目录下有哪些文件”观察 openrig 的日志。如果日志里显示请求转发到了 1234 端口并且返回了内容说明链路通了。如果 Claude Code 报错说连不上先检查 openrig 是否真的在运行、端口是否被占用。这一步最容易卡在“Claude Code 不认 openrig 的地址”。有些工具需要你显式设置环境变量指向本地代理地址比如把它的 base URL 环境变量改成 openrig 监听的地址。具体变量名看工具文档Claude Code 和 Codex 各有一套。6. 常见问题与排查技巧实录6.1 报错速查表报错关键词可能原因排查方向cc switch local proxy failed代理层没起来或端口冲突检查 openrig 进程和端口占用handling codex endpoint /responses接口路径不匹配确认下游服务是否支持该路径organization has disabled claude subscription账号订阅权限问题检查账号状态或改用 API 方式ignoring unrecognized configuration setting配置字段名写错对照文档核对字段拼写node.js vXX is not yet releasedNode 版本号不存在改用 LTS 版本codex 无法加载组织设置登录态或组织配置问题重新登录或检查组织权限6.2 独家避坑经验第一个坑是“配置改了但没生效”。很多工具会缓存配置改完 YAML 后要重启 openrig 和下游工具否则读的还是旧配置。我习惯改完配置先重启一遍再测。第二个坑是“端口冲突”。本地模型服务、openrig、工具自带的代理可能都想用同一个端口。启动前用lsof -i :端口号或 Windows 的netstat -ano | findstr 端口号查一下别让它们打架。第三个坑是“环境变量没传进去”。你在终端里 export 的变量只对当前终端会话有效。如果你用图形化方式启动工具它可能读不到你终端里的变量。这种情况要么在系统层面设置变量要么在启动脚本里显式传入。第四个坑是“模型名对不上”。YAML 里写的模型名必须和下游服务实际提供的模型名完全一致大小写、连字符都不能错。LM Studio 里加载的模型名和它 API 返回的模型名有时不一样以 API 返回的为准。6.3 日志排查的正确姿势出问题时日志是第一手资料。openrig 一般会打印请求转发的目标地址、请求体大小、响应状态码。先看请求有没有发出去再看发到了哪里最后看返回了什么。如果请求根本没发出去问题在 openrig 或工具配置如果发出去了但目标地址不对问题在 YAML 的 provider 配置如果地址对但返回错误问题在下游模型服务。按这个链路一段段排查比盲目改配置高效得多。注意排查时把日志级别调到 debug能看到完整的请求和响应。但 debug 日志可能包含敏感内容排查完记得调回去别把带密钥的日志提交到仓库。7. 我个人的一些使用体会折腾这套东西最大的感受是配置的复杂度不会消失只会转移。openrig 把分散在各个工具里的配置集中到了一处代价是你多了一个需要理解和维护的中间层。对于只用一个工具、只接一个模型的人来说这层可能显得多余但只要你同时用 Claude Code 和 Codex、还要在本地模型和第三方接口之间切换这层的价值就体现出来了。我现在的工作流是本地模型接 Claude Code 做日常的代码补全和简单重构第三方接口接 Codex 做需要更强推理的任务。两套配置都在同一份 YAML 里切换时只改 tools 段的 provider 引用不用去动每个工具自己的配置文件。这个体验比之前一个个改要顺太多。最后分享一个小技巧把常用的几套配置写成 YAML 锚点比如“本地开发”“远程推理”“离线测试”三套 provider 组合切换时只改一行引用。这样你既保留了灵活性又不用每次重写整段配置。配置这东西写得越像代码、越可复用维护起来就越轻松。