1. openrig 到底在解决什么问题第一次看到openrig这个名字很容易把它和一堆“AI 编程工具”混在一起。毕竟热词里全是 Claude Code、Codex、YAML、Node.js 这些词看起来像是又一个套壳客户端。但真正用过一段时间之后我的判断是它更像是一个把本地模型、云端模型、命令行 Agent 和项目配置统一收拢的“接线盒”。你可以这样理解Claude Code 和 Codex 各自都是一套能读写代码、执行命令、理解项目的智能体工具但它们默认都希望你用官方账号、官方模型、官方网络环境。而现实情况是很多开发者手里有本地模型比如通过 LM Studio 跑的模型、有第三方 API、有多个不同厂商的模型额度还想在 VS Code 里统一调用。openrig 的价值就在于它试图用一份 YAML 配置把这些分散的入口串起来让 Claude Code、Codex 这类工具能够指向你自定义的模型端点。它解决的问题非常具体模型来源碎片化本地一个模型、云端一个模型、公司内网一个模型切换起来要改环境变量、改配置文件非常麻烦。工具配置不统一Claude Code 有自己的配置方式Codex 有自己的登录和端点设置VS Code 插件又是一套。项目级配置缺失不同项目可能需要不同的模型、不同的上下文长度、不同的工具权限但大多数工具只支持全局配置。排查困难一旦出现cc switch local proxy failed while handling codex endpoint /responses这类报错很多人根本不知道是网络问题、配置问题还是模型不支持。openrig 适合谁来参考我认为有三类人第一类是想在本地把 Claude Code 或 Codex 跑起来、但不想完全依赖官方订阅的开发者第二类是需要频繁在多个模型之间切换、做对比测试的 AI 应用开发者第三类是想把 AI 编程工具接入自己项目工作流、需要项目级配置管理的团队。哪怕你只是刚装完 Node.js、还在研究node.js是干什么的这篇文章也会尽量把每一步讲清楚。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML而不是 JSON 或 TOMLopenrig 选择 YAML 作为核心配置格式这个决定背后有很实际的考量。JSON 虽然通用但不支持注释写配置时没法标注“这个字段是给 Codex 用的”“这个模型端点仅限内网”。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述多个模型、多个工具、多个项目覆盖规则时层级会变得很深。YAML 的优势在于支持注释你可以直接在配置里写# 这是本地 LM Studio 的端点几个月后回来看还能看懂。层级直观用缩进表达嵌套模型列表、工具映射、项目覆盖可以写得很清晰。多文档支持一个文件里可以用---分隔多段配置适合区分默认配置和项目配置。生态成熟Node.js 生态里有js-yaml、yaml等成熟解析库读取和校验都不难。但 YAML 也有坑。最大的坑就是缩进必须用空格不能用 Tab。我见过太多人复制粘贴配置后报错排查半天发现是编辑器自动把空格转成了 Tab。另一个坑是冒号后面必须加空格model:gpt-4和model: gpt-4在 YAML 里是完全不同的结果前者会被解析成一个字符串而不是键值对。提示如果你用 VS Code 编辑 YAML建议安装 YAML 插件它会实时提示缩进错误和语法问题能省掉大量排查时间。2.2 为什么依赖 Node.js 生态热词里反复出现node.js、node.js安装教程、安装node.js这不是偶然。openrig 以及 Claude Code、Codex 的很多命令行工具都是基于 Node.js 运行的。原因很简单跨平台Node.js 在 Windows、macOS、Linux 上都能跑一套代码不用为每个系统单独编译。npm 生态安装和更新工具只需要一条npm install -g命令依赖管理方便。异步 IO 适合 Agent 场景AI 编程工具需要同时处理文件读写、命令执行、网络请求Node.js 的事件循环模型正好匹配。社区工具丰富YAML 解析、HTTP 代理、命令行参数解析都有现成库。但 Node.js 的版本管理是个大坑。热词里有一条error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这就是典型的版本问题。很多人看到教程里写nvm install 24就跟着敲结果那个版本根本还没发布或者当前网络环境下拉不到。我的建议是不要盲目追最新版选 LTS 版本最稳。截至我写这篇文章时Node.js 20 LTS 和 22 LTS 是兼容性最好的选择。检查是否安装 Node.js 很简单node -v npm -v如果两条命令都能输出版本号说明环境没问题。如果提示command not found或不是内部或外部命令那就需要先安装。Windows 用户去 Node.js 官网下载 LTS 安装包一路下一步即可macOS 用户可以用 HomebrewLinux 用户建议用 nvm 管理版本避免权限问题。2.3 本地模型与云端模型的统一接入逻辑openrig 最核心的设计是把“模型端点”抽象成一个可配置项。无论你是用 LM Studio 跑本地模型还是用第三方 API 调云端模型在配置里都表现为一个baseUrl加一个apiKey。这种抽象的好处是Claude Code 或 Codex 不需要知道背后到底是本地还是云端它只负责把请求发到你配置的端点。端点再决定把请求转发给谁。这就像家里的插线板不管你插的是台灯、电脑还是充电器插线板只负责供电不关心设备是什么。具体来说一个典型的模型配置大概长这样models: - name: local-qwen provider: openai-compatible baseUrl: http://127.0.0.1:1234/v1 apiKey: local-key model: qwen2.5-coder-7b - name: cloud-deepseek provider: openai-compatible baseUrl: https://api.example.com/v1 apiKey: ${DEEPSEEK_API_KEY} model: deepseek-coder这里有几个细节值得展开。第一provider写openai-compatible是因为大多数本地模型服务和第三方 API 都兼容 OpenAI 的接口格式这样一套代码就能适配多种后端。第二apiKey用${DEEPSEEK_API_KEY}这种环境变量引用方式避免把密钥硬编码在配置文件里尤其是当你要把配置提交到 Git 仓库时这一点非常重要。第三model字段是实际传给后端的模型名称必须和后端支持的名称完全一致否则会出现the gpt-5.6-sol model is not supported这类报错。2.4 项目级覆盖与全局默认的取舍openrig 的配置设计里我比较欣赏的一点是支持项目级覆盖。也就是说你可以有一个全局默认配置然后在具体项目目录下放一个.openrig.yaml只写需要覆盖的字段。为什么要这样设计因为实际开发中不同项目对模型的需求差异很大。比如一个前端项目可能只需要一个轻量模型做代码补全。一个涉及大量数据处理的 Python 项目可能需要上下文更长的模型。一个公司内部项目可能需要指向内网端点而不是公网 API。如果所有配置都写全局切换项目时就要手动改来改去很容易出错。项目级覆盖的逻辑是先加载全局配置再用项目配置里的字段逐层覆盖。这样你只需要在项目里写差异部分比如# .openrig.yaml model: local-qwen contextLength: 32768其他没写的字段自动继承全局配置。这种“默认加覆盖”的模式在配置管理里是非常经典且实用的设计。3. 核心细节解析与实操要点3.1 环境准备Node.js 与包管理器的正确安装姿势在动手配置 openrig 之前环境准备是最容易翻车的一步。我见过太多人卡在node.js安装这一步要么是版本不对要么是权限问题要么是网络问题。Windows 用户的建议去 Node.js 官网下载 LTS 版本的.msi安装包。安装时勾选“Add to PATH”这样命令行里才能直接调用node和npm。安装完成后重启终端否则 PATH 不会生效。如果公司网络有限制可能需要配置 npm 镜像源但这一步要谨慎确保使用的是可信来源。macOS 用户的建议# 用 Homebrew 安装 brew install node20 # 或者用 nvm 管理多版本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 20 nvm use 20Linux 用户的建议优先用 nvm不要用apt install nodejs因为系统源里的 Node.js 版本往往很旧而且权限管理容易出问题。nvm 安装的 Node.js 都在用户目录下不需要 sudo升级和切换都方便。安装完成后验证一下node -v # 应该输出 v20.x.x 或 v22.x.x npm -v # 应该输出 10.x.x 或更高 which node # Linux/macOS 查看安装路径 where node # Windows 查看安装路径注意如果你之前用系统包管理器装过 Node.js又用 nvm 装了一个可能会出现版本冲突。建议先卸载系统版本的 Node.js再统一用 nvm 管理。3.2 YAML 配置文件的结构设计与字段说明openrig 的配置文件通常放在用户主目录下的.openrig目录里或者项目根目录下。一个完整的配置结构大致分为几个部分全局设置、模型列表、工具映射、项目覆盖。全局设置部分version: 1 defaultModel: local-qwen logLevel: info timeout: 120000version字段用于配置格式版本管理未来如果配置结构有变化可以通过版本号做兼容处理。defaultModel指定默认使用哪个模型当工具没有明确指定模型时就用这个。logLevel控制日志详细程度排查问题时可以改成debug。timeout是请求超时时间单位毫秒本地模型响应慢的话可以适当调大。模型列表部分models: - name: local-qwen provider: openai-compatible baseUrl: http://127.0.0.1:1234/v1 apiKey: local model: qwen2.5-coder-7b contextLength: 32768 maxTokens: 4096 temperature: 0.2这里每个字段都有实际作用。contextLength告诉工具这个模型支持多长的上下文避免发送超长请求导致报错。maxTokens限制单次生成的最大 token 数防止模型输出过长内容。temperature控制随机性写代码场景建议用较低的值比如 0.1 到 0.3这样输出更稳定。工具映射部分tools: claude-code: model: local-qwen env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234 ANTHROPIC_API_KEY: local codex: model: cloud-deepseek env: OPENAI_BASE_URL: https://api.example.com/v1 OPENAI_API_KEY: ${DEEPSEEK_API_KEY}这部分是 openrig 的核心价值所在。它把不同工具需要的环境变量统一管理起来你不需要手动去设置ANTHROPIC_BASE_URL或OPENAI_BASE_URLopenrig 会在启动工具时自动注入。3.3 本地模型服务的启动与验证如果你打算用本地模型LM Studio 是一个比较友好的选择。它的图形界面让模型下载和启动变得很简单同时它会暴露一个兼容 OpenAI 格式的本地端点。启动步骤下载并安装 LM Studio。在模型市场里搜索并下载一个代码能力较强的模型比如 Qwen2.5-Coder 系列。进入“Local Server”标签页选择刚下载的模型点击“Start Server”。默认端点通常是http://127.0.0.1:1234/v1。验证本地端点是否可用curl http://127.0.0.1:1234/v1/models如果返回一个 JSON 列表里面包含你加载的模型名称说明服务正常。如果连接被拒绝检查 LM Studio 的服务器是否真的启动了以及端口是否被占用。提示本地模型的响应速度取决于你的硬件。7B 参数的模型在普通笔记本上可能每秒只能生成几个 token14B 或更大的模型会更慢。如果你追求流畅体验建议至少 16GB 内存最好有独立显卡。3.4 Claude Code 与 Codex 的接入差异Claude Code 和 Codex 虽然都是 AI 编程工具但它们的接入方式有差异这也是 openrig 需要做工具映射的原因。Claude Code 通常读取ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。如果你想让 Claude Code 调用本地模型就需要把ANTHROPIC_BASE_URL指向本地端点。但这里有个问题Claude Code 的请求格式和 OpenAI 格式并不完全一样所以本地端点需要做一层转换。有些本地服务支持 Anthropic 格式有些不支持需要提前确认。Codex 则通常读取OPENAI_BASE_URL和OPENAI_API_KEY。它的请求格式更接近 OpenAI 标准所以对接本地模型或第三方 API 相对容易。但热词里出现的cc switch local proxy failed while handling codex endpoint /responses说明在切换端点时可能会遇到代理层的问题。这类问题通常是因为端点路径不对比如少写了/v1或者代理没有正确处理/responses这个路径。我的经验是先用 curl 直接测试端点确认端点本身可用再通过 openrig 接入工具。这样可以排除是端点问题还是配置问题。4. 实操过程与核心环节实现4.1 从零开始搭建 openrig 配置环境假设你现在什么都没有我们从零开始走一遍完整流程。第一步确认 Node.js 环境node -v npm -v如果没有输出先安装 Node.js LTS 版本。第二步安装 openrignpm install -g openrig如果网络较慢可以加长超时时间npm install -g openrig --fetch-timeout120000第三步初始化配置openrig init这个命令会在用户主目录下生成一个默认配置文件通常是~/.openrig/config.yaml。你可以用任何文本编辑器打开它。第四步编辑配置。以下是一个最小可用配置version: 1 defaultModel: local-qwen models: - name: local-qwen provider: openai-compatible baseUrl: http://127.0.0.1:1234/v1 apiKey: local model: qwen2.5-coder-7b contextLength: 32768 maxTokens: 4096 temperature: 0.2 tools: claude-code: model: local-qwen codex: model: local-qwen第五步验证配置openrig validate如果配置有语法错误这个命令会指出具体行号和问题。常见错误包括缩进不一致、冒号后缺空格、字段名拼写错误。第六步启动工具openrig run claude-code # 或者 openrig run codexopenrig 会读取配置注入环境变量然后启动对应的工具。4.2 参数计算上下文长度与超时时间怎么定配置里有两个参数经常让人纠结contextLength和timeout。这两个值不是随便填的需要根据实际情况计算。上下文长度方面模型本身有一个最大上下文限制比如 32768 token。但你不能把contextLength直接设成这个最大值因为输入内容本身要占 token包括你的代码、对话历史、系统提示。输出内容也要占 token也就是maxTokens。实际可用输入长度 contextLength-maxTokens- 系统提示占用。假设模型最大上下文是 32768你设置maxTokens为 4096系统提示大约占 1000 token那么实际可用于代码和对话的输入大约是 32768 - 4096 - 1000 27672 token。对于大多数单文件代码任务这个长度足够了。但如果你要处理整个项目的代码可能需要更大的上下文模型或者用检索增强的方式只发送相关文件。超时时间方面本地模型的生成速度可以用一个简单公式估算预计生成时间 maxTokens / 每秒生成token数比如你的模型每秒生成 10 个 tokenmaxTokens设为 4096那么最坏情况下需要 409.6 秒。这时候timeout如果还是默认的 120000 毫秒120 秒肯定会超时。所以本地模型的timeout建议设大一些比如 300000 毫秒甚至 600000 毫秒。注意超时时间设得太长也有副作用。如果端点真的挂了你会等很久才收到错误。建议先用小maxTokens测试确认链路通畅后再调大。4.3 项目级配置的覆盖实践假设你有一个前端项目想用轻量模型做补全另一个后端项目想用更强的模型做重构。这时候项目级配置就派上用场了。在前端项目根目录创建.openrig.yamlmodel: local-qwen maxTokens: 2048 temperature: 0.1在后端项目根目录创建.openrig.yamlmodel: cloud-deepseek maxTokens: 8192 temperature: 0.3当你在前端项目目录下运行openrig run claude-code时openrig 会先加载全局配置再用项目配置覆盖model、maxTokens和temperature这三个字段其他字段保持不变。这种设计的好处是你不需要为每个项目写完整配置只需要写差异部分。而且项目配置可以提交到 Git 仓库团队成员拉取后自动生效保证团队使用统一的模型设置。4.4 日志与调试出问题时先看什么openrig 的日志是排查问题的第一手资料。默认日志级别是info只输出关键信息。当你遇到问题时可以把日志级别改成debuglogLevel: debug然后重新运行工具观察输出。重点看几个地方配置加载路径确认 openrig 读取的是你修改的那个配置文件而不是另一个位置的旧配置。环境变量注入确认ANTHROPIC_BASE_URL或OPENAI_BASE_URL被正确设置。请求端点确认请求发往的 URL 和你预期的一致。响应状态码401 通常是密钥问题404 通常是路径问题500 通常是后端模型问题。如果日志里出现cc switch local proxy failed while handling codex endpoint /responses说明代理层在处理 Codex 的/responses路径时失败了。这时候要检查端点是否支持/responses路径有些本地服务只支持/chat/completions。代理配置是否正确转发了请求体和请求头。是否有防火墙或安全软件拦截了本地请求。5. 常见问题与排查技巧实录5.1 安装与版本类问题速查问题现象可能原因解决方法node: command not foundNode.js 未安装或 PATH 未配置重新安装 LTS 版本勾选 Add to PATH重启终端error installing 24.21.0: node.js v24.21.0 is not yet released指定了未发布的版本改用 LTS 版本如nvm install 20npm install -g权限报错没有全局安装权限用 nvm 管理 Node.js避免 sudoopenrig: command not found全局安装未生效检查 npm 全局 bin 目录是否在 PATH 中YAML 解析报错缩进用了 Tab 或冒号后缺空格用空格缩进冒号后加空格用 YAML 插件校验5.2 模型连接类问题排查模型连接问题是最常见的表现也多种多样。我整理了一个排查顺序按这个顺序走基本能定位到问题。第一步确认端点是否存活curl -v http://127.0.0.1:1234/v1/models如果连不上说明本地服务没启动或者端口不对。第二步确认模型名称是否正确curl http://127.0.0.1:1234/v1/models | grep -i qwen如果返回的模型列表里没有你配置的名称说明模型名称写错了或者模型没加载。第三步测试对话接口curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-coder-7b,messages:[{role:user,content:hello}]}如果这一步能返回内容说明端点本身没问题问题出在 openrig 配置或工具接入层。第四步检查 openrig 日志确认环境变量注入是否正确。5.3 工具接入类问题排查Claude Code 和 Codex 在接入自定义端点时有一些特有的坑。Claude Code 的坑主要在于请求格式。它默认使用 Anthropic 的 Messages API 格式而不是 OpenAI 的 Chat Completions 格式。如果你的本地端点只支持 OpenAI 格式就需要一个转换层。有些本地服务内置了 Anthropic 兼容模式需要在启动时开启。Codex 的坑主要在于路径和认证。热词里提到的cc switch local proxy failed while handling codex endpoint /responses就是一个典型例子。Codex 可能使用/responses路径而不是/chat/completions如果你的代理或端点不支持这个路径就会失败。解决方法是确认端点支持的路径或者在 openrig 配置里做路径重写。还有一个常见问题是your organization has disabled claude subscription access for claude code这通常和账号权限有关不是配置问题。如果你遇到这个提示说明当前账号无法使用 Claude Code 的官方订阅服务需要考虑改用 API 密钥方式或其他模型。5.4 性能与稳定性优化心得本地模型用起来最大的感受就是“慢”。但慢不一定是模型的问题很多时候是配置没调好。第一减少不必要的上下文。每次请求都发送整个项目代码不仅慢还可能超出上下文限制。建议只发送当前文件和相关文件或者用.openrigignore排除不需要的文件。第二调整maxTokens。如果你只是做代码补全不需要生成很长的内容把maxTokens设小一些比如 1024 或 2048能明显减少等待时间。第三用流式输出。如果工具支持流式输出开启后你能看到内容逐步生成体验会好很多即使总时间不变。第四本地模型量化。如果硬件资源有限可以选择量化版本的模型比如 Q4 量化体积更小、速度更快但质量会有一定下降。需要在速度和质量之间做权衡。第五避免频繁切换模型。每次切换模型本地服务可能需要重新加载模型到内存这个过程很耗时。如果要在多个模型间对比建议分批测试而不是频繁切换。提示如果你发现本地模型响应越来越慢检查一下内存占用。有些本地服务不会自动释放之前的模型导致内存越占越多。重启服务通常能解决。6. 我踩过的坑与实操建议6.1 配置文件位置混乱导致的“改了没生效”我最开始用 openrig 时遇到过一个很典型的问题改了配置但工具行为没变化。排查了半天发现是配置文件位置不对。openrig 会按优先级查找配置项目目录下的.openrig.yaml优先于用户主目录下的~/.openrig/config.yaml。我当时改的是全局配置但项目目录下有一个旧的.openrig.yaml覆盖了它。这个坑的教训是改配置前先确认 openrig 实际读取的是哪个文件。可以在配置里加一个明显的标记比如把logLevel改成debug然后运行工具看日志确认加载路径。6.2 环境变量与配置文件冲突另一个常见问题是环境变量和配置文件冲突。比如你在 shell 里设置了OPENAI_BASE_URL但 openrig 配置里也设置了baseUrl两者不一致时到底哪个生效我的经验是openrig 注入的环境变量通常会覆盖 shell 里已有的同名变量但具体行为取决于工具的实现。为了避免混乱建议统一在 openrig 配置里管理不要在 shell 里额外设置。如果确实需要临时覆盖可以在运行命令前用env查看当前环境变量确认没有冲突。6.3 本地模型“看起来能用但实际不能用”有些本地模型在简单对话测试时表现正常但一接入 Claude Code 或 Codex 就出问题。这通常是因为模型不支持工具调用function calling而 Claude Code 和 Codex 依赖这个能力。模型的输出格式不符合工具预期比如该返回 JSON 时返回了纯文本。模型的上下文长度不够处理稍大的文件就截断。选择本地模型时不要只看参数量要看它是否针对代码场景做过优化是否支持工具调用。Qwen2.5-Coder、DeepSeek-Coder 这类专门面向代码的模型通常比通用模型更适合。6.4 关于密钥管理的建议配置文件里写 API 密钥是大忌尤其是当配置要提交到 Git 时。我的做法是配置文件里只写${ENV_VAR_NAME}这样的占位符。真正的密钥放在.env文件或系统环境变量里。.env文件加入.gitignore避免误提交。团队协作时每个人维护自己的.env配置文件共享。这样即使配置文件泄露密钥也不会暴露。而且换密钥时只需要改环境变量不用改配置文件。6.5 版本升级的注意事项openrig、Claude Code、Codex 这些工具都在快速迭代版本升级可能带来配置格式变化。我的建议是升级前先备份当前配置文件。查看升级说明确认是否有破坏性变更。升级后先用openrig validate校验配置。如果新版本有问题可以回退到旧版本npm 支持安装指定版本npm install -g openrig1.2.3。不要盲目追最新版尤其是生产环境。等新版本稳定一段时间后再升级能避免很多意外问题。6.6 一个实用的小技巧配置模板化如果你经常需要切换不同的模型组合可以准备几份配置模板比如config-local.yaml、config-cloud.yaml、config-mixed.yaml。需要哪套就把哪套复制成config.yaml。更进一步可以用符号链接或者环境变量指定配置路径实现快速切换。# 用环境变量指定配置路径 OPENRIG_CONFIG~/.openrig/config-local.yaml openrig run claude-code这样你不需要每次手动改配置只需要切换环境变量即可。对于需要频繁对比不同模型效果的场景这个技巧能省不少时间。6.7 关于网络环境的稳妥处理在配置端点时确保你使用的网络环境是稳定且合规的。本地模型的好处是不依赖外部网络只要本地服务正常就能稳定使用。如果使用云端 API建议选择正规、可信的服务提供商并遵守相关服务条款。网络请求超时、连接中断等问题优先检查本地网络配置和端点可用性不要使用任何不合规的网络工具。我在实际使用中本地模型和云端 API 各有优劣。本地模型响应慢但数据不出本机适合处理敏感代码云端 API 响应快但依赖网络适合日常开发。openrig 的价值就在于让你能在两者之间灵活切换而不需要改代码或重装工具。