1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 这个词在无线电、矿机、测试台架这些圈子里太常见了。但把 openrig 和 Claude Code、Codex、YAML、Node.js 这几个词摆在一起看方向就清楚了这是一个围绕 AI 编程助手做本地配置编排的工具核心工作是把 Claude Code、Codex 这类命令行 AI 编码代理的接入参数、模型端点、代理规则用 YAML 统一管理起来再通过 Node.js 运行时把配置注入到对应的工具里。说白了openrig 解决的是一个很具体的痛点。现在用 Claude Code 或者 Codex 的人越来越多但这两个工具各自的配置方式完全不一样Claude Code 走的是自己的 settings 体系Codex 走的是 config.toml 加环境变量那一套如果你还想在两者之间切换模型供应商、切换本地模型、切换不同的 API 端点每次都要手动改配置文件、改环境变量、重启终端。openrig 想做的事情就是把这些散落在各处的配置收拢到一份 YAML 里用一套统一的描述方式去驱动多个 AI 编码工具。它适合谁三类人最需要。第一类是同时用 Claude Code 和 Codex 的开发者手上有多套模型接入方案来回切换很烦。第二类是想把本地模型比如通过 LM Studio 跑起来的模型接进 Claude Code 的人需要处理端点映射和协议转换。第三类是在团队里做开发环境标准化的人希望把 AI 编码工具的配置纳入版本管理而不是每个人各配各的。我自己的判断是openrig 这类工具的价值不在于它多复杂而在于它把配置这件事从手工活变成了可复现的工程产物。这一点在多人协作或者多机环境下尤其明显。2. 核心设计思路与方案选型拆解2.1 为什么用 YAML 做配置层选 YAML 而不是 JSON 或者 TOML这个决定背后有很实际的考量。JSON 不支持注释而 AI 编码工具的配置里有大量需要说明的地方比如某个端点为什么这么写、某个模型别名对应哪个实际模型这些都需要注释。TOML 虽然支持注释但嵌套结构写起来比较啰嗦尤其是当你要描述多个工具、多个供应商、多个模型映射的时候TOML 的表格语法会让人写得很累。YAML 的优势在于层级表达自然缩进即结构写多供应商多模型的配置时阅读体验最好。而且 YAML 在 DevOps 圈子里已经是事实标准Kubernetes、Ansible、GitHub Actions 都在用开发者对它没有学习成本。openrig 选择 YAML本质上是在降低用户的配置门槛。但 YAML 也有坑最大的问题就是缩进敏感和类型推断。比如on、yes、no这些词在 YAML 1.1 里会被解析成布尔值如果你把模型名写成no就会出问题。还有端口号如果写成8080没问题但写成08080就可能被当成八进制。这些细节后面在实操部分会展开讲。2.2 Node.js 作为运行时的合理性openrig 用 Node.js 做运行时这个选择我觉得是权衡之后的最优解。原因有几个第一Claude Code 本身就是 Node.js 生态的产物它是通过 npm 分发的安装方式就是npm install -g。Codex 虽然有自己的分发渠道但在很多场景下也是通过 npm 或者 Node 工具链来管理的。openrig 用 Node.js 写能直接复用这套生态不需要用户额外装 Python 或者 Go 运行时。第二Node.js 处理 JSON 和 YAML 的能力很成熟js-yaml、yaml这些库稳定可靠读写配置文件、做 schema 校验都很方便。第三Node.js 的跨平台支持好Windows、macOS、Linux 上行为一致这对于一个需要覆盖多平台的配置工具来说很重要。你在 Windows 上写的配置拿到 Ubuntu 上应该能直接用Node.js 能保证这一点。当然Node.js 也有它的问题最主要的就是版本管理。不同项目依赖不同的 Node 版本是常态openrig 如果对 Node 版本有要求用户就得用 nvm 或者 fnm 来切换。这一点在实际使用中会成为一个高频问题后面会专门讲。2.3 统一配置驱动多工具的核心逻辑openrig 最核心的设计是一份配置多个目标。它的工作流程大致是这样的读取用户写的 openrig.yaml解析出每个工具Claude Code、Codex的配置段根据配置段生成对应工具能识别的配置文件格式把生成的文件写到工具期望的位置必要时设置环境变量或者启动代理进程这个流程的关键在于格式转换和位置映射。Claude Code 期望的配置格式和 Codex 期望的格式不一样openrig 要在中间做翻译。同时不同操作系统上配置文件的存放位置也不一样Windows 在%APPDATA%下macOS 和 Linux 在~/.config或者~/.claude下openrig 要能正确识别。这种设计的好处是用户只需要学一套配置语法坏处是 openrig 必须紧跟上游工具的变化。Claude Code 和 Codex 都在快速迭代配置格式随时可能变openrig 的维护压力不小。这是所有做配置抽象层的工具都要面对的问题。3. 环境准备与依赖安装实操3.1 Node.js 版本选择与安装openrig 对 Node.js 版本有要求我实测下来建议用 Node.js 20 LTS 或者 22 LTS。不要用太新的版本比如 24.x因为有些依赖库还没跟上会出现error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错。也不要用过老的版本18 以下很多现代语法不支持。安装方式按平台来Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包一路下一步就行。安装完之后打开 PowerShell 或者 CMD输入node -v和npm -v确认版本。如果显示的不是你刚装的版本说明 PATH 里有多个 Node需要用where node查一下路径。macOS 用户我强烈建议用 nvm 或者 fnm 来管理 Node 版本不要直接用官网 pkg 安装。因为 macOS 上权限问题比较多用版本管理器可以避免EACCES错误。安装 nvm 的命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后nvm install 20然后nvm use 20。Ubuntu 用户可以用 NodeSource 的源来装curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完同样用node -v验证。注意如果你之前用 apt 装过 nodejs先sudo apt remove nodejs卸掉否则会出现两个 Node 打架的情况。3.2 Claude Code 与 Codex 的安装确认openrig 本身不负责安装 Claude Code 和 Codex它只负责配置。所以在用 openrig 之前你得先确保这两个工具已经装好了。Claude Code 的安装npm install -g anthropic-ai/claude-code装完之后claude --version能输出版本号就说明 OK。如果提示your organization has disabled claude subscription access for claude code那是账号权限问题不是安装问题需要找管理员开通。Codex 的安装方式取决于你用的版本。如果是 CLI 版本通常也是通过 npm 或者官方安装包。装完之后codex --version验证。提示Claude Code 和 Codex 都建议装在全局不要装在项目本地否则 openrig 在生成配置时可能找不到可执行文件路径。3.3 openrig 的获取与初始化openrig 的获取方式一般是 clone 仓库或者通过 npm 安装。假设是通过 npmnpm install -g openrig装完之后在项目目录下执行初始化openrig init这个命令会生成一份openrig.yaml模板文件。如果你不想用模板也可以手动创建。初始化之后你会得到一个类似这样的结构version: 1 tools: claude-code: enabled: true provider: anthropic model: claude-sonnet-4-20250514 codex: enabled: true provider: openai model: gpt-5.6-sol这份配置就是 openrig 的核心后面所有的操作都围绕它展开。4. openrig.yaml 配置详解与参数计算4.1 配置文件整体结构openrig.yaml 的结构设计是分层的顶层是版本号和工具列表每个工具下面有自己的配置段。我建议按这个顺序组织version: 1 defaults: timeout: 30000 retry: 2 providers: anthropic: base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY openai: base_url: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY local: base_url: http://127.0.0.1:1234/v1 api_key_env: LOCAL_API_KEY tools: claude-code: enabled: true provider: anthropic model: claude-sonnet-4-20250514 env: ANTHROPIC_BASE_URL: ${providers.anthropic.base_url} codex: enabled: true provider: openai model: gpt-5.6-sol env: OPENAI_BASE_URL: ${providers.openai.base_url}这个结构的好处是 providers 和 tools 分离多个工具可以复用同一个 provider 定义。比如你既想让 Claude Code 用本地模型又想让 Codex 用本地模型只需要在 providers 里定义一次 local然后在两个工具里都引用它。4.2 provider 段的参数含义provider 段描述的是模型服务的接入信息核心参数有这几个base_urlAPI 端点地址。这个地址决定了请求发到哪里。如果你用官方服务就填官方地址如果你用本地模型就填本地地址比如 LM Studio 默认的http://127.0.0.1:1234/v1。api_key_envAPI key 从哪个环境变量读取。openrig 不会把 key 明文写在 YAML 里而是通过环境变量注入这是安全实践。headers额外的请求头。有些第三方服务需要特定的 header比如自定义的认证头或者版本头。timeout请求超时时间单位毫秒。默认 30000 也就是 30 秒如果模型响应慢可以调大。这里有个容易踩的坑base_url的结尾要不要带/v1。不同服务的约定不一样OpenAI 兼容接口通常要求带/v1但有些代理服务不需要。我的经验是先按服务商文档来如果报 404 就试着加或者去掉/v1。4.3 模型映射与别名机制openrig 支持模型别名这个功能在多模型切换场景下非常实用。你可以在配置里定义别名models: fast: provider: local model: qwen2.5-coder-7b strong: provider: anthropic model: claude-sonnet-4-20250514然后在工具里引用别名tools: claude-code: model: fast这样你切换模型的时候只需要改一处不用去每个工具里改。而且别名让配置的可读性更好fast比qwen2.5-coder-7b直观多了。注意别名不能和实际模型名冲突否则 openrig 解析时会优先当成别名处理导致找不到模型。4.4 环境变量注入与优先级openrig 在生成配置时会把 provider 里的信息转换成环境变量注入到工具的运行环境里。这里有一个优先级问题需要搞清楚工具自身配置文件里的设置优先级最高openrig 注入的环境变量次之系统全局环境变量优先级最低也就是说如果 Claude Code 自己的 settings.json 里已经写了 base_url那 openrig 注入的就不会生效。所以用 openrig 之前建议先把工具自身的配置文件清理干净避免冲突。5. 完整实操流程从零到跑通5.1 第一步确认 Node 环境先跑一遍node -v npm -v确认 Node 是 20 或 22 LTS。如果版本不对用 nvm 切换nvm install 20 nvm use 20Windows 用户如果没有 nvm可以去下载 nvm-windows安装后同样用nvm use 20切换。5.2 第二步安装 openrig 并初始化npm install -g openrig openrig init初始化完成后检查生成的 openrig.yaml确认路径和内容。5.3 第三步配置 provider 和 tool根据你的实际情况修改 openrig.yaml。如果你用官方服务填官方 base_url如果你用本地模型填本地地址。API key 通过环境变量设置export ANTHROPIC_API_KEYyour_key_here export OPENAI_API_KEYyour_key_hereWindows PowerShell 用$env:ANTHROPIC_API_KEYyour_key_here5.4 第四步应用配置openrig apply这个命令会读取 openrig.yaml生成各工具需要的配置文件并写入到正确的位置。执行完之后你会看到类似这样的输出[openrig] applying configuration... [openrig] claude-code: wrote ~/.claude/settings.json [openrig] codex: wrote ~/.codex/config.toml [openrig] done.5.5 第五步验证配置生效启动 Claude Codeclaude然后在里面问一个简单问题看是否能正常返回。如果返回了说明配置生效。Codex 同理跑codex然后测试。如果报错先看错误信息里的端点地址是不是你配置的那个。如果端点不对说明配置没写进去检查 openrig apply 的输出。5.6 第六步切换模型测试修改 openrig.yaml 里的 model 字段换成另一个模型再跑一次openrig apply重启工具看是否切换成功。这一步能验证 openrig 的配置驱动能力是否正常工作。6. 常见问题与排查技巧实录6.1 配置不生效的排查顺序配置不生效是最常见的问题排查顺序建议这样确认 openrig apply 执行成功没有报错确认生成的配置文件路径正确用cat或者编辑器打开看看内容确认工具读取的是这个路径的配置有些工具支持多路径可能读的是另一个确认环境变量已经设置用echo $ANTHROPIC_API_KEY检查重启工具很多工具只在启动时读配置6.2 端点连接失败的典型原因端点连接失败通常有这几个原因现象可能原因解决方法Connection refused本地服务没启动启动 LM Studio 或其他本地服务404 Not Foundbase_url 路径不对检查是否需要加 /v1401 UnauthorizedAPI key 无效重新设置环境变量403 Forbidden账号权限问题检查账号是否有权限Timeout网络或服务响应慢调大 timeout 参数6.3 YAML 语法错误的快速定位YAML 语法错误往往报错信息不直观。我常用的定位方法是openrig validate这个命令会做语法校验并指出错误行号。如果没有这个命令可以用 Python 快速验证python3 -c import yaml; yaml.safe_load(open(openrig.yaml))报错会指出具体行号和问题类型。6.4 多工具配置冲突的处理如果你同时用 Claude Code 和 Codex而且它们都读同一个环境变量就会冲突。比如两个工具都读OPENAI_API_KEY但你想让它们用不同的 key。解决办法是在 tool 段里单独覆盖tools: claude-code: env: OPENAI_API_KEY: ${CLAUDE_OPENAI_KEY} codex: env: OPENAI_API_KEY: ${CODEX_OPENAI_KEY}这样每个工具读自己的 key互不干扰。6.5 版本升级后的配置迁移Claude Code 和 Codex 升级后配置格式可能变openrig 也需要跟着升级。升级前建议先备份 openrig.yamlcp openrig.yaml openrig.yaml.bak然后升级 openrignpm update -g openrig升级后跑openrig validate检查配置是否还兼容不兼容的话按提示修改。7. 进阶用法与个人经验7.1 把 openrig.yaml 纳入版本管理我强烈建议把 openrig.yaml 提交到 Git 仓库但 API key 不要写进去。用环境变量引用然后在 README 里说明需要设置哪些环境变量。这样团队里每个人 clone 下来设置好自己的 key跑一次openrig apply就能得到一致的开发环境。7.2 多环境配置切换如果你有多个环境比如公司内网和家里可以用多个配置文件openrig apply --config openrig.work.yaml openrig apply --config openrig.home.yaml或者用环境变量控制providers: anthropic: base_url: ${ANTHROPIC_BASE_URL:-https://api.anthropic.com}这样默认用官方地址设置了环境变量就用环境变量的值。7.3 本地模型接入的注意事项把本地模型接入 Claude Code 或 Codex 时最大的问题是协议兼容性。Claude Code 期望的是 Anthropic 的 API 格式Codex 期望的是 OpenAI 的格式。如果你的本地模型只支持 OpenAI 格式接 Claude Code 就需要一个转换层。openrig 本身不做协议转换它只做配置注入所以你需要确保本地服务支持目标工具期望的协议。LM Studio 支持 OpenAI 兼容接口所以接 Codex 比较直接。接 Claude Code 的话需要看 LM Studio 是否支持 Anthropic 格式或者用一个中间代理做转换。7.4 配置调试的小技巧调试配置时我习惯用openrig apply --dry-run先看会生成什么不实际写入。这样可以在不破坏现有配置的情况下检查配置是否正确。如果 openrig 不支持 dry-run可以先把配置文件备份apply 之后对比差异。另一个技巧是用openrig show查看当前生效的配置确认 openrig 解析出来的结果和你预期的一致。7.5 性能与稳定性建议openrig 本身很轻量性能不是问题。稳定性方面主要注意两点一是 Node 版本要稳定不要用太新的二是配置文件要简洁不要写太多不必要的配置配置越复杂出问题的概率越高。我自己的 openrig.yaml 一般控制在 50 行以内只写必要的 provider 和 tool 配置其他都用默认值。这样维护起来最省心。