1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架项目毕竟 rig 在英文里有“装配、支架”的意思。但结合 Claude Code、Codex、YAML、Node.js 这几个关键词放在一起答案就清晰了openrig 是一套围绕 AI 编程助手尤其是 Claude Code 和 Codex 这类命令行智能体做本地配置编排、模型接入与运行环境管理的开源工具链思路。它的核心价值在于把散落在各处的配置文件、模型端点、代理转发规则、环境变量统一收拢到一份可读可维护的 YAML 里让“换模型”“切端点”“调参数”这些高频操作从手工改文件变成改一行配置。我接触这类工具是因为一个很现实的痛点手上有 Claude Code、Codex CLI还想接本地跑的模型或者第三方兼容端点结果每换一次模型就要翻文档、改环境变量、重启终端稍不注意就报cc switch local proxy failed while handling codex endpoint /responses这种让人头大的错误。openrig 这类编排方案要解决的正是这种“配置地狱”。它适合三类人一是刚装完 Claude Code 或 Codex、还在摸索配置的新手二是需要在多个模型端点之间频繁切换的开发者三是想把 AI 编程助手接入团队统一环境、需要可复现配置的工程团队。需要先说明的是openrig 目前更多是一种“配置编排范式”而非某个单一官方产品网络上关于它的讨论集中在 YAML 结构设计、Node.js 运行环境、以及和 Claude Code / Codex 的对接方式上。所以这篇内容我会把它当作一套可落地的工程实践来讲涉及的具体字段和路径基于常见做法补全你照着改就能用。2. 整体设计思路为什么用 YAML 做编排中枢2.1 配置即代码把混乱的环境变量收进一份文件传统做法里Claude Code 和 Codex 的配置分散在环境变量、各自主目录下的 JSON、以及 shell 的 rc 文件里。你想换个模型得同时改三四个地方改完还不一定生效因为有的工具读的是启动时快照。openrig 的思路是“配置即代码”用一份 YAML 描述所有端点、模型、密钥引用和启动参数再由一个轻量 Node.js 脚本把它翻译成各个工具认识的环境变量和配置文件。为什么是 YAML 而不是 JSON 或 TOMLJSON 不支持注释你没法在配置里写“这行是给测试环境用的”TOML 表达嵌套结构时层级一深就啰嗦。YAML 支持注释、缩进直观、天然适合表达“端点列表 每个端点的参数”这种结构。而且 YAML 在 DevOps 圈子里认知度极高K8s、CI 流水线都用它团队里没人需要重新学。2.2 Node.js 作为运行时跨平台与生态的双重考量选 Node.js 做运行时不是随便定的。Claude Code 和 Codex 的 CLI 本身就是 Node.js 生态的产物用同一套运行时能避免“装了两个版本的 Python 结果依赖打架”的问题。Node.js 的跨平台一致性也好Windows、macOS、Linux 上同一份脚本行为基本一致这对需要“在 Ubuntu 服务器和 Windows 桌面都跑”的场景很关键。提示安装 Node.js 时优先选 LTS 版本。网上常见的error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错多半是版本号写错或者镜像源还没同步换成当前 LTS 主线即可。2.3 端点抽象层让 Claude Code 和 Codex 共用一套模型定义openrig 设计里最巧妙的一点是把“模型”和“工具”解耦。你在 YAML 里定义的是“我有一个叫 deepseek-chat 的端点它的 base_url 是什么、走什么协议”至于这个端点是被 Claude Code 用还是被 Codex 用是启动时决定的。这样一来同一份模型定义可以同时喂给两个工具切换工具不用重写配置。这个抽象层还顺带解决了协议差异问题。Claude Code 走的是 Anthropic 风格的 messages 接口Codex 走的是 OpenAI 风格的 responses 接口两者字段不一样。openrig 在中间做了一层适配把统一配置翻译成各自需要的格式这也是为什么它能缓解cc switch local proxy failed while handling codex endpoint /responses这类协议不匹配的报错。3. 核心细节拆解YAML 结构怎么设计才不踩坑3.1 顶层结构providers、models、tools 三段式我实测下来最稳的 YAML 结构是分三段providers描述服务提供方和鉴权models描述具体模型和参数tools描述 Claude Code、Codex 各自的启动偏好。这样分层的好处是改一处不影响另一处。比如你只是换了个 API key只动 providers想调 temperature只动 models。providers: - name: local-ollama base_url: http://127.0.0.1:11434/v1 api_key: ${LOCAL_KEY} protocol: openai models: - name: qwen-local provider: local-ollama model_id: qwen2.5-coder temperature: 0.2 max_tokens: 8192 tools: claude-code: default_model: qwen-local env_prefix: ANTHROPIC codex: default_model: qwen-local env_prefix: OPENAI注意api_key用的是${LOCAL_KEY}这种引用写法而不是把密钥明文写进 YAML。这是硬性习惯YAML 文件经常会被提交到仓库或者分享给别人明文密钥一旦泄露就是事故。引用写法让真正的密钥留在系统环境变量或.env文件里。3.2 模型参数temperature 和 max_tokens 怎么定很多人配置模型时随手填参数结果要么回答太发散要么被截断。temperature 控制随机性写代码场景建议 0.1 到 0.3太高会生成语法正确但逻辑跑偏的代码做创意文案可以到 0.7 以上。max_tokens 要结合模型上下文窗口来定比如模型总窗口 32k你留 8k 给输出比较稳妥剩下的留给输入和对话历史。这里有个容易忽略的点不同工具对 max_tokens 字段名要求不同。Claude Code 认max_tokens某些 OpenAI 兼容端点认max_completion_tokens。openrig 的适配层会根据 tools 段里的协议类型自动映射但如果你手写配置直接喂给工具就得自己对齐字段名否则会出现“参数传了但没生效”的诡异现象。3.3 端点协议openai 与 anthropic 的字段差异协议字段是踩坑重灾区。OpenAI 风格端点的请求体里消息角色是system、user、assistant而 Anthropic 风格把 system 单独拎出来做顶层字段。如果你把一个 OpenAI 兼容端点硬塞给 Claude Code就会出现角色字段对不上、system 提示词丢失的问题。对比项OpenAI 风格Anthropic 风格消息角色system/user/assistantuser/assistantsystem 独立端点路径/v1/chat/completions 或 /v1/responses/v1/messages鉴权头Authorization: Bearerx-api-key最大输出字段max_tokens / max_completion_tokensmax_tokensopenrig 在 providers 段里用protocol字段标记协议类型适配层据此转换。你只要标对了剩下的字段映射它来处理。标错的直接后果就是请求发出去但返回 400或者返回内容为空。4. 实操过程从装 Node.js 到跑通第一个端点4.1 环境准备Node.js 安装与版本校验第一步永远是环境。Windows 用户去 Node.js 官网下载 LTS 安装包一路下一步即可安装时记得勾选“Add to PATH”。macOS 用brew install node或者官网 pkg 都行。Ubuntu 上我更推荐用 NodeSource 的源比系统自带的版本新curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs装完必须校验别跳过node -v npm -v如果node -v报 command not found八成是 PATH 没配好。Windows 上重开一个终端窗口通常就好了因为 PATH 是启动时读取的。Ubuntu 上检查/usr/bin/node是否存在不存在说明安装没成功。注意不要同时装多个 Node.js 版本管理器nvm、fnm、系统包还都往 PATH 里塞版本冲突会导致 CLI 工具行为诡异。选一个用就行。4.2 安装 Claude Code 与 Codex CLIClaude Code 的安装走 npm 全局安装npm install -g anthropic-ai/claude-codeCodex CLI 同理具体包名以官方文档为准。装完用claude --version和codex --version验证。如果报权限错误Linux/macOS 上加sudo或者配置 npm 的全局目录到用户目录下避免权限问题npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH这一步的坑在于全局安装的包在切换 Node.js 版本后会“消失”因为不同版本的全局目录是隔离的。所以定好一个 Node.js 版本就别频繁换。4.3 编写 openrig 配置文件并生成工具配置环境好了开始写 YAML。我建议放在项目根目录或者~/.config/openrig/config.yaml。写完用一个 Node.js 脚本读取并生成各工具需要的配置。核心逻辑是读 YAML遍历 tools 段把对应模型的 base_url、api_key、model_id 拼成环境变量写进一个 shell 可 source 的文件或者直接写进工具的主目录配置文件。const fs require(fs); const yaml require(js-yaml); const cfg yaml.load(fs.readFileSync(./config.yaml, utf8)); const model cfg.models.find(m m.name cfg.tools[claude-code].default_model); const provider cfg.providers.find(p p.name model.provider); const envLines [ export ANTHROPIC_BASE_URL${provider.base_url}, export ANTHROPIC_API_KEY${process.env[provider.api_key.replace(/[${}]/g, )]}, export ANTHROPIC_MODEL${model.model_id}, ]; fs.writeFileSync(./.openrig.env, envLines.join(\n));生成后source .openrig.env再启动 Claude Code它就会读到你指定的端点。Codex 同理只是环境变量前缀换成 OPENAI 系列。4.4 验证端点连通性先 curl 再上工具配置写完别急着开工具先用 curl 直接打端点确认网络和鉴权没问题curl -s http://127.0.0.1:11434/v1/models \ -H Authorization: Bearer $LOCAL_KEY能列出模型列表说明端点是通的。这一步能帮你把“配置问题”和“网络问题”分开。我见过太多人一上来就开 Claude Code报错了不知道是配置错还是端点没起来白白浪费时间。先 curl 通再上工具排查路径清晰得多。5. 常见问题与排查技巧实录5.1 端点报错速查表报错现象可能原因排查方向cc switch local proxy failed代理层协议不匹配检查 protocol 字段是否标对/responses 404端点不支持 responses 接口换 chat/completions 路径401 Unauthorized密钥未注入或格式错检查环境变量是否 source模型不支持报错model_id 拼写错对照端点模型列表核对返回空内容max_tokens 太小或角色映射错调大输出上限检查协议5.2 密钥注入失败的三种典型情况第一种是环境变量名写错YAML 里引用${LOCAL_KEY}但系统里设的是LOCAL_API_KEY名字对不上自然取不到。第二种是 source 顺序问题先启动了工具再 source 环境文件工具读的是旧环境。第三种是 Windows 下环境变量作用域问题用户级变量和系统级变量在不同终端里可见性不一样。我的习惯是写一个启动脚本把 source 和启动工具绑在一起避免手动顺序出错#!/bin/bash source ./.openrig.env exec claude $这样每次都是先注入环境再启动杜绝顺序问题。5.3 本地模型接入的额外注意点接本地模型比如通过 Ollama 或 LM Studio 起的服务时有两个坑。一是本地服务默认可能只监听 127.0.0.1如果你在容器或远程环境里跑工具就连不上需要让服务监听 0.0.0.0。二是本地模型的上下文窗口往往比云端小配置里 max_tokens 别照抄云端的值否则请求直接被拒。提示本地模型首次加载会有冷启动延迟curl 测试时给足超时时间别以为没响应就是配置错了。5.4 组织策略限制类报错的应对有时候会遇到your organization has disabled claude subscription access这类提示这通常是账号层面的策略限制不是本地配置能解决的。遇到这种检查是不是用错了账号或者换用 API key 方式而非订阅方式接入。这类问题排查时先确认账号状态再回头看本地配置别在配置上死磕。6. 进阶玩法多端点切换与团队协作6.1 用 profile 实现一键切换当你有多个端点本地、测试、生产时可以在 YAML 里加 profile 概念每个 profile 指定一组默认模型。切换时只改一个环境变量OPENRIG_PROFILE脚本据此选不同的模型组合。这比手动改配置高效得多也避免了改错文件。profiles: dev: claude-code: qwen-local codex: qwen-local prod: claude-code: cloud-model codex: cloud-model6.2 团队共享配置的脱敏处理团队协作时YAML 可以进仓库但密钥绝对不能。做法是把密钥全部用环境变量引用仓库里只放结构。再配一份.env.example说明需要哪些变量新人 clone 后复制成.env填自己的值。这样配置可复现密钥不泄露。6.3 配置版本化与回滚把 openrig 配置纳入 git 管理每次改配置都提交。出问题时git diff一眼看出改了什么git checkout一键回滚。我踩过的坑是改配置没记录结果工具行为变了半天找不到原因后来养成提交习惯就再没这个问题。7. 我在实际使用中的几点体会折腾 openrig 这套东西最大的收获不是省了多少配置时间而是把“环境不确定性”这个变量控制住了。以前换个模型要试半天现在改一行 YAML 重跑脚本就行出问题也能快速定位是配置层还是端点层。另外提醒一句YAML 对缩进极其敏感用空格别用 Tab编辑器里打开“显示空白字符”能帮你避开大量低级错误。最后任何配置改动都先在测试端点验证通过再上生产这个习惯能帮你省下很多深夜排查的时间。