1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里常指设备支架、钻机平台。翻了翻社区讨论和几个仓库的 README 才反应过来这是一套围绕 AI 编程助手做本地化编排的开源工具集核心解决的是把 Claude Code、Codex 这类命令行智能体统一管起来的问题。你可以把它理解成一个“调度中枢”模型从哪来、请求走哪条链路、配置怎么复用、多个工具之间怎么切换这些琐碎但极其影响体验的事情openrig 想一次性收拢。为什么这个东西会冒出来因为现在用 AI 写代码的人手里往往不止一个工具。Claude Code 擅长长上下文推理和终端命令执行Codex 在补全和特定语言任务上有自己的手感本地还有 LM Studio 跑着的开源模型。问题是每个工具都有自己的配置文件、环境变量、认证方式装一个配一遍换一个再配一遍时间全耗在折腾环境上。openrig 的定位就是把这些差异抹平用一份 YAML 描述清楚“我要用哪个模型、走哪个端点、带什么参数”然后让不同工具共享这套定义。它适合谁如果你只是偶尔用网页版问几个问题那确实用不上。但如果你已经在终端里跑 Claude Code 或者 Codex CLI或者正准备从网页版迁移到命令行工作流openrig 能省掉大量重复配置。尤其是那些需要在多个模型供应商之间来回切换的开发者比如白天用云端模型处理复杂重构晚上切到本地模型跑批量任务openrig 的价值就体现出来了。它不改变工具本身的能力但把“管理成本”这一块压到了很低。我自己的感受是这类编排工具的出现是必然的。AI 编程助手已经从“新鲜玩意”变成了日常生产力工具一旦进入日常稳定性和可维护性就比功能多寡更重要。openrig 踩的正是这个点。2. 核心设计思路与方案选型拆解2.1 为什么用 YAML 做配置层openrig 选择 YAML 作为配置格式这个决定看起来平淡实际上很关键。JSON 也能描述配置但写起来太啰嗦多一层嵌套就多一堆括号和引号手写容易出错。TOML 更简洁但表达嵌套结构时不够直观。YAML 在可读性和表达力之间找到了平衡点缩进即层级列表和字典混排很自然而且几乎所有编程语言都有成熟的解析库。更重要的是YAML 对非程序员也相对友好。很多用 Claude Code 的人并不是专业后端可能是数据分析师、运维、甚至产品经理他们不需要理解 JSON Schema只要能照着示例改几个字段就行。openrig 的配置文件里模型定义、端点地址、认证信息、工具映射各占一块结构清晰改起来不容易搞乱。注意YAML 对缩进极其敏感Tab 和空格混用会直接报解析错误。建议统一用两个空格缩进并且在编辑器里开启“显示空白字符”这样能一眼看出问题。2.2 多工具统一编排的架构逻辑openrig 的架构可以粗略分成三层。最底层是“模型接入层”负责和不同的 API 端点通信不管是云端服务还是本地 LM Studio都抽象成统一的调用接口。中间是“配置管理层”读取 YAML 文件把模型定义、工具偏好、环境变量解析成运行时配置。最上层是“工具适配层”针对 Claude Code、Codex 等不同 CLI 工具生成它们各自认识的配置格式或者启动参数。这种分层的好处是解耦。新增一个模型供应商只需要在接入层加一个适配器新增一个 CLI 工具只需要在适配层加一个转换规则。用户侧感知到的就是改改 YAML其他都不用动。我试过在同一个项目里同时配 Claude Code 和 Codex切换的时候只改一行active_tool字段剩下的 openrig 自己处理。2.3 和直接改环境变量相比的优势有人可能会问我直接设ANTHROPIC_API_KEY或者改 Codex 的 config 文件不就行了为什么要多一层短期看确实没必要但一旦你的工具超过两个、模型超过三个环境变量就会变成一团乱麻。哪个变量对应哪个工具、哪个端点用哪个密钥、本地模型和云端模型的超时设置不一样这些信息散落在 shell 配置文件、工具私有配置、项目级.env里排查问题的时候非常痛苦。openrig 把这些集中到一份 YAML 里相当于给配置做了“单一事实来源”。改一处所有工具同步生效。而且 YAML 可以纳入版本控制团队协作时直接提交到仓库新人拉下来就能用不用在群里问“那个密钥填哪里”。这一点在实际项目里价值很大我见过太多因为环境配置不一致导致的“在我机器上能跑”问题。3. 环境准备与基础依赖安装3.1 Node.js 的正确安装方式openrig 本身是 Node.js 项目所以第一步是把 Node.js 装好。这里有个坑很多人踩过直接用系统包管理器装版本往往偏旧。比如 Ubuntu 默认源里的 Node.js 可能还是 18.x而 openrig 要求 20.x 以上。更麻烦的是有些教程让你用apt install nodejs之后还要单独装npm结果版本对不上后面各种报错。我的建议是直接去 Node.js 官网下载 LTS 版本。LTS 是长期支持版稳定性和兼容性都有保障不会像 Current 版那样隔几周就变。下载页面会根据你的系统自动推荐安装包Windows 选.msimacOS 选.pkgLinux 用户可以用 NodeSource 的脚本或者直接下二进制包。安装完成后打开终端验证node -v npm -v两条命令都能输出版本号才算成功。如果node -v报“command not found”说明 PATH 没配好Windows 用户检查安装时有没有勾选“Add to PATH”Linux/macOS 用户检查/usr/local/bin是否在 PATH 里。提示如果你之前装过旧版本 Node.js建议先卸载干净再装新版。Windows 上可以用“应用和功能”卸载macOS 上如果用 Homebrew 装的先brew uninstall nodeLinux 上apt remove nodejs npm之后还要apt autoremove清理残留依赖。3.2 Claude Code 与 Codex 的安装要点Claude Code 的安装方式取决于你用的平台。官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-code装完之后在终端输入claude应该能启动。如果提示权限不足Linux/macOS 用户前面加sudo但更推荐用 nvm 管理 Node.js 环境这样全局包不需要 sudo 也不会污染系统目录。Codex 的安装类似也是 npm 包npm install -g openai/codex不过 Codex 对 Node.js 版本更敏感我遇到过在 Node 18 上装完启动直接崩的情况换成 20 LTS 就正常了。所以前面强调 Node.js 版本不是小题大做。两个工具都装好后先别急着配 openrig单独跑一下确认它们本身能工作。Claude Code 首次启动会引导你登录或者填 API KeyCodex 也有类似的初始化流程。这一步走通了再引入 openrig 做统一管理否则出了问题分不清是工具本身的问题还是编排层的问题。3.3 YAML 解析依赖与常见安装报错openrig 运行时会依赖 YAML 解析库通常 npm 安装时会自动处理。但如果你看到类似error installing 24.21.0: node.js v24.21.0 is not yet released这种报错说明 npm 试图安装一个不存在的 Node.js 版本根源还是本地 Node.js 版本和项目要求不匹配。解决办法是回到 3.1 节确认 Node.js 版本符合要求。另一个常见问题是网络原因导致 npm 包下载失败。如果你在公司内网或者网络环境受限可以配置 npm 镜像源npm config set registry https://registry.npmmirror.com这个镜像源同步频率很高绝大多数包都能正常拉取。配完之后再执行安装命令速度会明显提升。4. openrig 配置文件详解与实操4.1 YAML 配置文件的基本结构openrig 的核心配置文件通常叫openrig.yaml放在项目根目录或者用户主目录下。一个最小可用的配置大概长这样version: 1 active_tool: claude-code models: - name: claude-sonnet provider: anthropic endpoint: https://api.anthropic.com api_key: ${ANTHROPIC_API_KEY} model_id: claude-sonnet-4-20250514 - name: local-qwen provider: openai-compatible endpoint: http://localhost:1234/v1 api_key: not-needed model_id: qwen2.5-coder-7b tools: claude-code: model: claude-sonnet extra_args: - --max-tokens - 8192 codex: model: local-qwen extra_args: - --temperature - 0.2这个结构里models定义可用的模型端点tools定义每个 CLI 工具用哪个模型、带什么参数。active_tool决定当前默认启动哪个工具。${ANTHROPIC_API_KEY}是环境变量引用语法openrig 读取时会自动替换成实际值这样密钥不用明文写在 YAML 里安全性更好。4.2 模型端点的配置技巧配置模型端点时有几个参数容易搞混。endpoint是 API 的基础地址不带具体路径。比如 Anthropic 的是https://api.anthropic.comOpenAI 兼容接口通常是http://localhost:1234/v1。model_id是实际传给 API 的模型标识不同供应商命名规则不一样Anthropic 用claude-sonnet-4-20250514这种带日期的格式本地 LM Studio 则用你加载的模型文件名。provider字段决定 openrig 用哪种协议去调用。目前常见的有anthropic、openai、openai-compatible几种。本地 LM Studio 和大多数开源模型服务都兼容 OpenAI 协议所以填openai-compatible就行。如果你用的是 DeepSeek 或者智谱的 API它们也提供 OpenAI 兼容接口同样用这个 provider。注意本地模型的api_key虽然用不上但有些 OpenAI 兼容实现会检查这个字段是否存在填个not-needed或者任意字符串即可不要留空。4.3 工具适配层的参数映射不同 CLI 工具接受的参数格式不一样。Claude Code 用--max-tokens这种长参数Codex 可能用-t或者配置文件里的字段。openrig 的extra_args就是用来处理这种差异的你在这里写的参数会原样传给对应的工具。我一般会把常用参数固化到 YAML 里比如 Claude Code 处理大文件时把--max-tokens调高Codex 做代码补全时把--temperature调低。这样切换工具的时候不用记每个工具的参数名openrig 帮你翻译好了。如果某个工具需要环境变量而不是命令行参数openrig 也支持在tools下面写env字段tools: claude-code: model: claude-sonnet env: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192这种写法比在 shell 里 export 一堆变量清爽得多而且跟着项目走换机器不用重新配。4.4 多环境配置的切换策略实际工作中经常需要区分环境比如开发时用本地模型省钱生产任务用云端模型保证质量。openrig 支持多份配置文件通过--config参数指定openrig --config openrig.dev.yaml run claude-code openrig --config openrig.prod.yaml run codex也可以把公共部分抽出来用 YAML 的锚点和引用来复用defaults: defaults api_key: ${API_KEY} timeout: 30 models: - name: fast-model : *defaults endpoint: http://localhost:1234/v1 model_id: qwen2.5-coder-7b - name: strong-model : *defaults endpoint: https://api.anthropic.com model_id: claude-sonnet-4-20250514defaults定义锚点: *defaults把公共字段合并进来。这样改超时时间只需要改一处所有模型同步生效。YAML 锚点在配置项多的时候特别有用能省掉大量重复。5. 实操流程从零跑通 openrig5.1 初始化项目与安装 openrig找一个空目录作为工作区执行mkdir my-ai-workspace cd my-ai-workspace npm init -y npm install openrig如果你希望全局可用加-g参数。安装完成后用npx openrig --version验证是否成功。看到版本号输出就说明基础环境没问题。接下来生成默认配置npx openrig init这个命令会在当前目录创建openrig.yaml模板里面包含注释和示例字段。我建议不要直接改模板而是复制一份改成自己的配置模板留着当参考。5.2 配置第一个模型端点以本地 LM Studio 为例先在 LM Studio 里加载一个模型启动本地服务默认端口是 1234。然后在openrig.yaml里添加models: - name: local-coder provider: openai-compatible endpoint: http://localhost:1234/v1 api_key: not-needed model_id: qwen2.5-coder-7b timeout: 60timeout设成 60 秒是因为本地模型首次加载比较慢默认的 30 秒可能不够。等模型常驻内存后可以调回 30。配好后用 openrig 的测试命令验证连通性npx openrig test local-coder这个命令会发一个简单的请求过去返回模型响应就说明配置正确。如果报连接拒绝检查 LM Studio 的服务有没有启动如果报模型不存在检查model_id和 LM Studio 里显示的模型名是否一致。5.3 绑定 Claude Code 并验证模型端点通了之后在tools里绑定 Claude Codeactive_tool: claude-code tools: claude-code: model: local-coder extra_args: - --max-tokens - 4096然后启动npx openrig run claude-codeopenrig 会读取配置把模型端点信息转换成 Claude Code 认识的环境变量和参数然后启动 Claude Code 进程。你应该能看到 Claude Code 正常启动并且用的是你配置的本地模型。这里有个细节Claude Code 默认会连 Anthropic 官方端点openrig 通过设置ANTHROPIC_BASE_URL之类的环境变量把它重定向到本地。如果你发现 Claude Code 还是连的官方服务检查 openrig 的日志输出看看环境变量有没有正确注入。5.4 切换 Codex 与参数微调切换到 Codex 只需要改active_toolactive_tool: codex tools: codex: model: local-coder extra_args: - --temperature - 0.1Codex 对温度参数比较敏感做代码生成时建议设低一点0.1 到 0.3 之间比较稳。太高了容易生成语法正确但逻辑奇怪的代码。启动命令换成npx openrig run codex如果你同时想跑两个工具openrig 也支持在命令里临时指定npx openrig run claude-code --model strong-model这样不用改配置文件就能临时切换模型适合做对比测试。6. 常见问题与排查技巧实录6.1 配置解析失败的几种典型情况YAML 解析错误是最常见的问题表现通常是启动时直接报YAMLException或者cannot parse config。排查步骤很简单先用在线 YAML 校验工具过一遍或者用 Python 的yaml.safe_load试解析。大多数情况下是缩进问题比如某个字段多了一个空格或者少了一个空格。另一个高频错误是环境变量引用没解析。如果你写了${ANTHROPIC_API_KEY}但 shell 里没有这个变量openrig 可能把它当成字面量传下去导致认证失败。解决办法是在启动前echo $ANTHROPIC_API_KEY确认变量存在或者在 YAML 里直接写值不推荐但调试时可以用。6.2 模型连接超时与重试策略本地模型服务偶尔会因为内存不足或者进程卡死导致连接超时。openrig 默认超时是 30 秒对于大模型推理可能不够。可以在模型定义里加timeout字段也可以配retry策略models: - name: local-coder provider: openai-compatible endpoint: http://localhost:1234/v1 api_key: not-needed model_id: qwen2.5-coder-7b timeout: 120 retry: max_attempts: 3 backoff: 2max_attempts: 3表示失败后重试两次backoff: 2表示每次重试间隔翻倍。这个配置对不稳定的本地服务很有效偶尔的抖动不会直接导致任务失败。6.3 工具启动后行为异常的排查有时候 openrig 启动成功了但 Claude Code 或者 Codex 的行为不对劲比如不响应输入、输出乱码、或者报模型不支持。这种情况先看 openrig 的日志通常会有injecting env或者passing args之类的记录确认参数有没有正确传递。如果日志显示参数正确但工具行为还是异常可能是工具版本和 openrig 的适配层不匹配。openrig 的适配规则是针对特定版本的工具写的工具升级后参数格式变了适配层可能没跟上。解决办法是查 openrig 的 release notes看有没有针对新版本的适配更新或者手动在extra_args里覆盖有问题的参数。6.4 常见问题速查表问题现象可能原因排查方法解决方式启动报 YAML 解析错误缩进不一致或 Tab 混用用在线校验工具检查统一用两个空格缩进模型连接被拒绝本地服务未启动或端口不对curl测试端点连通性启动服务或修正 endpoint认证失败 401API Key 未设置或过期检查环境变量和密钥有效性重新生成密钥并更新配置工具无响应参数传递错误或版本不匹配查看 openrig 日志中的参数注入更新 openrig 或手动覆盖参数输出乱码编码格式不一致检查终端编码和模型输出编码统一设为 UTF-8切换工具后配置未生效缓存了旧配置清除 openrig 缓存目录重启 openrig 或加--no-cache这张表是我在实际使用中慢慢攒出来的基本上覆盖了八成以上的常见故障。遇到新问题的时候先对照这张表过一遍能省不少排查时间。7. 进阶用法与个人经验补充7.1 用 openrig 管理多项目配置如果你同时维护多个项目每个项目用的模型和工具可能不一样。openrig 支持项目级配置在项目根目录放一个openrig.yaml启动时会优先读取当前目录的配置找不到再往上找用户主目录的全局配置。这个查找逻辑和.gitignore、.eslintrc类似用起来很自然。我一般把通用模型定义放在全局配置里项目特有的参数放在项目配置里。比如全局配好claude-sonnet和local-qwen两个模型项目 A 用前者项目 B 用后者各自在项目配置里指定active_tool和model就行。7.2 结合 VS Code 的工作流优化虽然 openrig 主要在终端里用但和 VS Code 配合也能提升效率。你可以在 VS Code 的tasks.json里定义任务一键启动 openrig{ version: 2.0.0, tasks: [ { label: Start Claude Code with openrig, type: shell, command: npx openrig run claude-code, problemMatcher: [] } ] }配好之后按CtrlShiftB就能启动不用切到终端敲命令。如果你用 VS Code 的 Claude Code 扩展也可以在设置里指定 openrig 生成的配置路径让扩展走同样的模型端点。7.3 我踩过的几个坑第一个坑是 YAML 里的布尔值。YAML 会把yes、no、on、off解析成布尔值如果你某个字段想写字符串no不加引号就会变成false。我配模型名称的时候写了个model_id: no结果解析出来是布尔值报错报了半天才找到原因。所以涉及可能被误解析的值一律加引号。第二个坑是环境变量展开的时机。openrig 读取 YAML 的时候展开${VAR}但如果你在extra_args里写了${VAR}它可能不会展开而是原样传给工具。这种时候要么在 shell 里先 export 好要么用 openrig 的env字段显式传递。第三个坑是本地模型的并发限制。有些本地服务同时只能处理一个请求如果你用 openrig 同时启动多个工具连同一个端点第二个请求会排队或者直接失败。解决办法是给每个工具配不同的模型实例或者错开启动时间。7.4 后续可以扩展的方向openrig 目前主要解决配置编排的问题但还有很多可以延伸的空间。比如结合 CI/CD 做自动化测试在流水线里用 openrig 切换不同模型跑回归或者做一个简单的 Web UI让不熟悉命令行的团队成员也能切换模型和工具。社区里已经有人在尝试把 openrig 和本地知识库结合让模型能读取项目文档再回答问题这个方向挺有意思。我个人最期待的是 openrig 能支持更多工具类型不只是 CLI还包括编辑器插件和桌面应用。如果能把所有 AI 编程入口都统一到一套配置下那开发体验会再上一个台阶。不过在那之前把现有的 Claude Code 和 Codex 用明白已经能省下不少折腾环境的时间了。