1. openrig 到底是个什么东西第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者开源机械臂项目。实际上结合它周围高频出现的 Claude Code、Codex、YAML、Node.js 这些词可以判断出它属于 AI 编程助手工具链里的一个配置编排层。简单说openrig 做的事情就是把 Claude Code、Codex 这类命令行 AI 编程工具以及它们背后要调用的模型服务、代理端点、环境变量用一份结构化的 YAML 文件统一管理起来让开发者不用每次手动去改一堆散落在各处的配置。它解决的核心痛点很具体。现在用 Claude Code 或者 Codex 的人越来越多但这两个工具各自的配置方式不一样Claude Code 依赖环境变量和 settings 文件Codex 走的是自己的 config 体系如果你还想在两者之间切换不同的模型后端比如今天用官方端点、明天换成 DeepSeek 或者本地 LM Studio手动改配置很容易出错。openrig 的思路就是把这些东西抽象成一份声明式的 YAML你只描述我要用哪个工具、连哪个端点、走哪个模型剩下的环境变量注入、路径拼接、启动参数组装全部由它来处理。适合谁来参考这份内容三类人最需要。第一类是刚接触 Claude Code 或 Codex被安装和配置卡住的开发者尤其是 Windows 环境下遇到各种路径和权限问题的第二类是已经在用这些工具但每次切换模型或端点都要翻文档、改配置效率很低的中级用户第三类是想把 AI 编程工具集成进团队工作流需要一套可复制、可版本管理的配置方案的技术负责人。不管你属于哪一类下面这些内容都是从实际踩坑里总结出来的不是照搬官方文档。2. 整体设计思路与方案选型拆解2.1 为什么用 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置载体这个决定背后有很实际的考量。JSON 的问题是写不了注释而 AI 工具链的配置里注释极其重要——你需要标注这个端点对应哪个模型这个 key 从哪申请什么情况下要改这个值。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述多个工具、多个端点、多层级的模型映射时TOML 的表格语法会变得很难读。YAML 的优势在于它天然适合表达层级关系而且支持锚点和引用这一点在 openrig 场景下特别有用。比如你定义了三个端点其中两个共享同一套请求头配置用 YAML 的锚点可以只写一次其他地方引用就行。另外 YAML 对多行字符串的支持也比 JSON 友好写系统提示词或者自定义指令的时候不用到处转义。注意YAML 对缩进极其敏感Tab 和空格混用是最常见的报错来源。建议在编辑器里把 Tab 自动转成 2 个空格VSCode 里搜 insert spaces 就能设置。2.2 为什么依赖 Node.js 生态Claude Code 和 Codex 的 CLI 版本都是基于 Node.js 分发的这是 openrig 必须依赖 Node.js 的根本原因。Node.js 在这里扮演的是运行时角色它提供了 npm 包管理能力让 Claude Code 和 Codex 可以通过全局安装的方式在终端里直接调用。同时 Node.js 的版本管理也很关键因为不同版本的 Claude Code 对 Node.js 版本有不同要求装错了版本会出现各种奇怪的报错。实际使用中Node.js 的 LTS 版本是最稳妥的选择。截至目前的经验Node.js 20.x 和 22.x 这两个 LTS 版本对 Claude Code 和 Codex 的兼容性最好。如果你用的是 Windows建议通过官方安装包安装不要用某些第三方包管理器因为路径注册方式不一样后面配置环境变量的时候容易出问题。2.3 配置分层全局层、项目层、会话层openrig 的设计里有一个很重要的分层思想理解了这个你就能明白为什么有些配置改了不生效。它把配置分成三层全局层存在用户主目录下对所有项目生效通常放 API key、默认端点、通用偏好设置项目层存在项目根目录只对当前项目生效放项目特定的模型选择、自定义指令、忽略规则会话层通过环境变量或命令行参数临时注入优先级最高适合临时切换模型做对比测试这个分层的意义在于你可以把敏感的 API key 放在全局层把项目相关的配置放在项目层并提交到版本控制团队成员拉下来就能用而不用每个人都去问 key 是什么。会话层则给了你最大的灵活性比如你想临时用 DeepSeek 跑一个任务不用改任何文件直接在启动命令前加环境变量就行。3. 核心细节解析与实操要点3.1 Node.js 环境准备的正确姿势安装 Node.js 看起来简单但这里踩坑的人最多。Windows 用户去官网下载 LTS 安装包一路下一步就行但有两个地方要注意。第一安装路径不要有中文和空格默认的C:\Program Files\nodejs\其实就带空格虽然大部分情况没问题但某些 npm 包在处理路径时会出幺蛾子建议改成C:\nodejs\这种干净路径。第二安装完成后一定要验证打开新的终端窗口执行node -v npm -v两个命令都能输出版本号才算成功。如果提示不是内部或外部命令说明环境变量没配好手动把 Node.js 安装目录加到系统 PATH 里。Ubuntu 用户建议用 NodeSource 的源来装比系统自带的版本新很多curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs装完之后同样用node -v验证。这里有个经验如果你之前用 apt 装过旧版本先sudo apt remove nodejs卸干净再装不然会出现两个版本打架的情况。提示网上有些教程会让你装 nvm 来管理 Node.js 版本这在需要频繁切换版本的场景下确实有用但对 openrig 来说不是必须的。如果你只用一个版本直接装 LTS 更省事。3.2 Claude Code 与 Codex 的安装差异这两个工具的安装方式有区别不能混为一谈。Claude Code 的 CLI 版本通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在终端输入claude就能启动。第一次启动会引导你登录或者配置 API key。这里有个常见问题如果你的组织禁用了 Claude 订阅访问会看到 your organization has disabled claude subscription access for claude code 这样的提示这时候你需要改用 API key 方式而不是订阅登录方式。Codex 的安装稍微复杂一点它有不同的分发渠道。通过 npm 安装的方式是npm install -g openai/codex但 Codex 对 Node.js 版本的要求更严格如果你看到 error installing 24.21.0: node.js v24.21.0 is not yet released 这类报错说明你的 npm 在尝试安装一个不存在的 Node.js 版本这通常是 npm 缓存或者源的问题执行npm cache clean --force后重试。3.3 YAML 配置文件的结构设计openrig 的 YAML 配置文件通常长这样我以一个实际用过的结构为例version: 1 defaults: tool: claude-code endpoint: official endpoints: official: base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY deepseek: base_url: https://api.deepseek.com api_key_env: DEEPSEEK_API_KEY model_map: claude-sonnet: deepseek-chat local: base_url: http://localhost:1234/v1 api_key_env: LMSTUDIO_KEY tools: claude-code: env: ANTHROPIC_BASE_URL: {{endpoint.base_url}} ANTHROPIC_API_KEY: {{env(endpoint.api_key_env)}} codex: config_path: ~/.codex/config.yaml env: OPENAI_BASE_URL: {{endpoint.base_url}}这个结构的关键在于endpoints和tools的分离。端点描述的是连到哪里工具描述的是怎么连。这样设计的好处是当你新增一个模型服务时只需要在 endpoints 里加一段所有工具都能复用。model_map则解决了不同服务商模型命名不一致的问题比如 Claude 叫 claude-sonnetDeepSeek 叫 deepseek-chat通过映射表自动转换。3.4 环境变量注入的时机问题这是最容易出错的地方。openrig 在启动工具之前会把 YAML 里定义的环境变量注入到子进程里但如果你是在已经打开的终端里手动 export 了变量两者会冲突。优先级是这样的会话层手动 export 项目层 全局层。也就是说如果你手动 export 了一个值YAML 里的配置就不会生效。实际排查的时候先用env | grep ANTHROPIC看看当前终端里有没有残留的环境变量。如果有要么 unset 掉要么就接受它覆盖 YAML 配置的事实。我个人的习惯是所有持久化配置都放 YAML临时测试才用 export测试完立刻关掉终端窗口避免污染后续会话。4. 实操过程与核心环节实现4.1 从零搭建 openrig 工作流的完整步骤假设你是一台全新的 Windows 机器下面是我实际走过一遍的流程。第一步装 Node.js。去官网下载 22.x LTS 的 Windows 安装包安装路径改成C:\nodejs安装时勾选自动添加到 PATH。装完打开新的 PowerShellnode -v应该输出v22.x.x。第二步装 Claude Code 和 Codex。这里建议先配置 npm 的国内镜像源不然下载速度会很慢npm config set registry https://registry.npmmirror.com npm install -g anthropic-ai/claude-code npm install -g openai/codex第三步创建 openrig 的配置目录。在用户主目录下建一个.openrig文件夹里面放config.yaml。Windows 下就是C:\Users\你的用户名\.openrig\config.yaml。第四步填入端点信息。如果你用官方服务endpoints 里配官方地址和对应的 key 环境变量名如果用第三方兼容端点把 base_url 换成对应的地址。这里要注意有些第三方端点虽然兼容 OpenAI 格式但路径不一样有的要加/v1有的不要这个必须看服务商的文档确认。第五步验证配置。openrig 一般会提供一个openrig check或者类似的命令来校验 YAML 语法和端点连通性。如果没有这个命令就手动启动一次 Claude Code看能不能正常对话。启动命令通常是openrig run claude-code这种形式。4.2 接入本地模型服务的参数计算很多人想用 LM Studio 或者类似工具跑本地模型然后让 Claude Code 调用。这里有几个参数必须算清楚。首先是上下文长度。本地模型的上下文窗口通常比云端小比如你跑一个 7B 的模型上下文可能只有 8K 或者 32K。而 Claude Code 默认会发送比较长的系统提示和文件内容如果超出本地模型的上下文限制请求会直接失败。解决办法是在 YAML 里给这个端点单独设置max_tokens和context_limit让 openrig 在发送前做截断。其次是并发数。本地模型的推理速度受限于你的显卡如果同时发多个请求每个都会变慢。在 YAML 里可以设置concurrency: 1强制串行处理。这个值官方端点可以设高一些本地端点建议就设 1。最后是超时时间。本地模型首次加载需要时间如果超时设得太短第一个请求会失败。建议本地端点的timeout设到 120 秒以上官方端点 30 秒就够了。4.3 在 VSCode 里集成 Claude CodeVSCode 有 Claude Code 的官方扩展装完之后可以在编辑器里直接调用。但扩展和 CLI 的配置是分开的扩展读的是 VSCode 的设置不是 openrig 的 YAML。如果你想让两者用同一套端点配置需要手动把 YAML 里的值同步到 VSCode 的 settings.json 里。具体做法是在 VSCode 的 settings.json 里加{ claude-code.environmentVariables: { ANTHROPIC_BASE_URL: 你的端点地址, ANTHROPIC_API_KEY: 你的key } }这样扩展启动的时候就会用这些环境变量。缺点是每次改 YAML 都要手动同步一次比较麻烦。如果你频繁切换端点建议还是以 CLI 为主VSCode 扩展只在固定端点下使用。4.4 Codex 接入第三方模型的配置方法Codex 默认连的是 OpenAI 的端点但通过改配置可以接入 DeepSeek 或者其他兼容 OpenAI 格式的服务。Codex 的配置文件通常在~/.codex/config.yaml内容大概是这样model: deepseek-chat provider: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY}这里的关键是base_url要带/v1因为 Codex 内部拼接路径的时候是按 OpenAI 的规范来的。如果你接的服务商不需要/v1就要在 base_url 里去掉或者在 openrig 层面做路径重写。还有一个坑是模型名称。Codex 会校验模型名是否在支持列表里如果你填了一个它不认识的模型名会报 the gpt-5.6-sol model is not supported 这类错误。解决办法是在配置里加上model_map把 Codex 认识的模型名映射到你实际要用的模型。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错报错信息原因解决方法node.js v24.21.0 is not yet releasednpm 缓存了不存在的版本号npm cache clean --force后重试your organization has disabled claude subscription access组织策略禁用了订阅登录改用 API key 方式配置command not found: claude全局安装路径不在 PATH 里手动把 npm 全局目录加到 PATHYAML 解析报错Tab 和空格混用编辑器设置 Tab 转 2 空格5.2 运行阶段的连接问题连接问题分两种一种是完全连不上一种是连上了但返回错误。完全连不上通常是 base_url 写错了或者本地服务没启动。排查方法是先用 curl 直接测端点curl -X POST https://你的端点/v1/chat/completions \ -H Authorization: Bearer 你的key \ -H Content-Type: application/json \ -d {model:模型名,messages:[{role:user,content:test}]}如果 curl 能通但 Claude Code 不通那就是 openrig 的环境变量注入有问题检查 YAML 里的变量名和工具实际读取的变量名是否一致。Claude Code 读的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYCodex 读的是OPENAI_BASE_URL和OPENAI_API_KEY名字对不上就不会生效。连上了但返回错误常见的是 401 和 404。401 是 key 无效或者没传对404 是路径不对。有些第三方端点要求 base_url 结尾不带斜杠有些要求带这个只能试。我的经验是先在 curl 里把路径试通再往 YAML 里填。5.3 模型切换后行为异常的排查切换模型后如果发现回答质量突然下降或者工具调用不工作先确认模型是否支持 function calling。Claude Code 和 Codex 都依赖 function calling 来执行终端命令和读写文件如果切换到的模型不支持这个能力工具就会退化成纯聊天模式。排查方法是看日志。Claude Code 启动时加--verbose参数可以看到详细的请求和响应。如果响应里没有 tool_calls 字段说明模型没返回工具调用要么是模型不支持要么是提示词没适配。这种情况下要么换回支持 function calling 的模型要么在 YAML 里给这个端点单独配置一套简化版的提示词。5.4 配置文件版本管理的经验openrig 的 YAML 文件建议提交到项目的版本控制里但 API key 绝对不能提交。做法是在 YAML 里只写环境变量名不写实际值然后在项目根目录放一个.env.example说明需要哪些变量。团队成员拉下来之后自己创建.env填入真实的 key.env加到.gitignore里。这样做的另一个好处是当端点配置需要调整时改 YAML 提交所有人都能同步到不用在群里发配置截图。我见过太多团队因为配置不同步导致我这里能跑你那里跑不了的问题用版本管理配置之后这类问题基本消失了。5.5 性能调优的几个实用参数如果你觉得 Claude Code 响应慢可以调这几个参数。max_tokens控制单次响应的最大长度设小一点能加快返回速度但可能截断长回答。temperature设低一些比如 0.2能让输出更稳定适合代码生成场景。timeout根据端点位置调整本地端点设长云端端点设短。还有一个容易被忽略的是retry次数。网络不稳定的时候适当的重试能避免请求失败但重试太多会拖慢整体速度。建议设 2 次超过 2 次还失败说明是端点本身的问题重试也没用。6. 我个人的一些实操体会用 openrig 这套东西有一段时间了最大的感受是配置的集中管理确实省心但前提是你得把 YAML 的结构设计好。我一开始把所有东西都塞在一个文件里后来端点多了之后变得很难维护改成按端点拆分成多个文件主配置里用include引用清晰了很多。另一个体会是不要过度追求自动化。有些配置项其实很少变手动改一下也就几秒钟的事硬要抽象成变量反而增加了理解成本。openrig 的价值在于管理那些频繁切换的配置比如端点和模型而不是把所有东西都抽象一遍。最后分享一个小技巧在 YAML 里给每个端点加一个description字段写清楚这个端点是干什么的、什么时候用。过几个月再回来看的时候你会感谢自己当初写了注释。