1. openrig 到底是个什么东西第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者开源机械臂项目。实际上结合它周边的关键词——Claude Code、Codex、YAML、Node.js——可以判断出openrig 是一套围绕 AI 编程助手尤其是 Claude Code 和 Codex 这类 CLI 工具搭建的本地配置与运行框架。它的核心价值在于把原本散落在各个工具、各个配置文件里的参数、模型接入信息、代理设置、环境变量统一收敛到一套可维护的结构里让开发者不用每次换模型、换工具就重新折腾一遍环境。我最初接触这类需求是因为同时用 Claude Code 和 Codex 两个 CLI 工具一个负责日常代码补全和重构一个负责跑批量任务和长上下文分析。结果两边各自有一套配置逻辑Claude Code 认~/.claude/settings.jsonCodex 认自己的 TOML 或 YAML 配置模型端点、API Key、超时时间、代理地址全都要分别维护。每次切换模型供应商比如从官方端点切到本地 LM Studio或者从 DeepSeek 切到 GLM就得改两三个文件改完还要重启终端验证。openrig 要解决的就是这个痛点用一份 YAML 描述清楚“我要用什么模型、走什么端点、给哪个工具用”然后由 Node.js 脚本负责把这份描述渲染成各个工具认识的配置格式。这套东西适合谁如果你只是偶尔用一下网页版 AI 对话那确实用不上。但如果你满足下面任意一条openrig 这类方案就值得花时间研究第一你同时在用两个以上的 AI 编程 CLI 工具第二你需要频繁在官方 API、第三方中转、本地模型之间切换第三你有团队协作需求希望把“怎么连模型”这件事标准化而不是每个人自己手改配置第四你经常遇到“organization has disabled claude subscription access”或者“model is not supported when using codex”这类报错想从根上理清配置关系。从热词里还能看到几个高频问题cc switch local proxy failed while handling codex endpoint /responses、codex无法加载组织设置、error installing 24.21.0: node.js v24.21.0 is not yet released。这些都不是孤立的 bug而是配置层、运行时层、网络层三个层面交织出来的症状。openrig 的思路就是把这三层拆开YAML 管配置层Node.js 管运行时和渲染具体的端点连通性交给工具自身去处理但配置模板里会预留好代理和超时参数。我自己的判断是openrig 不是一个“装完就能用”的成品软件更像是一套约定和脚手架。你需要理解它的目录结构、YAML schema、渲染逻辑然后根据自己的工具链做适配。下面我会从设计思路、核心细节、实操过程、问题排查四个维度把这套东西拆开讲清楚。2. 整体设计与思路拆解2.1 为什么选 YAML 作为配置中枢openrig 用 YAML 而不是 JSON 或 TOML 作为核心配置格式这个选择背后有实际考量。JSON 不支持注释而 AI 工具配置里经常需要标注“这个 Key 是哪天申请的”“这个端点只在内网可用”注释很重要。TOML 虽然支持注释但嵌套结构写起来比较啰嗦尤其是当你要描述“多个工具、多个模型、多个端点”的矩阵关系时TOML 的[table.subtable]语法会让人眼花。YAML 的缩进式结构天然适合表达层级关系而且支持锚点和引用可以在不同工具配置之间复用同一段模型定义。举个例子假设你有三个模型端点官方 Claude、本地 LM Studio、第三方 DeepSeek。两个工具Claude Code 和 Codex。如果用 JSON你要写六份端点配置每个工具三份改一个端点地址要改两处。用 YAML 的锚点可以这样写models: claude_official: claude_official endpoint: https://api.anthropic.com model: claude-sonnet-4-20250514 timeout: 60 lmstudio_local: lmstudio_local endpoint: http://127.0.0.1:1234/v1 model: local-model timeout: 120 tools: claude_code: default_model: *claude_official fallback_model: *lmstudio_local codex: default_model: *lmstudio_local fallback_model: *claude_official这样改一处端点两个工具同时生效。这是 openrig 设计里最实用的一点。很多人一开始觉得 YAML 缩进容易出错但只要你用 VS Code 装一个 YAML 插件开启 schema 校验缩进问题基本可以避免。2.2 Node.js 在其中的角色定位openrig 选择 Node.js 作为运行时而不是 Python 或 Go原因也很直接Claude Code 和 Codex 的 CLI 本身就是 Node.js 生态的产物。Claude Code 通过 npm 分发Codex CLI 也有 npm 包。用 Node.js 写渲染脚本可以直接复用这些工具的类型定义和配置解析逻辑不需要跨语言调用。而且 Node.js 的fs、path、os模块处理跨平台路径非常方便Windows、macOS、Linux 三端都能跑。具体来说openrig 的 Node.js 脚本做三件事第一读取openrig.yaml用js-yaml解析成 JavaScript 对象第二根据当前操作系统和已安装工具决定输出哪些配置文件、输出到什么路径第三把 YAML 里的模型定义渲染成各工具需要的格式比如 Claude Code 的settings.json、Codex 的config.toml或config.yaml。这个过程是幂等的每次运行都会覆盖生成所以不用担心手动改乱了配置。这里有个细节值得注意Node.js 版本选择。热词里出现了error installing 24.21.0: node.js v24.21.0 is not yet released说明有人尝试安装一个不存在的版本。截至我写这篇内容时Node.js 的 LTS 版本是 22.x24.x 还在 Current 阶段。openrig 这类工具建议用 LTS 版本因为js-yaml、commander这些依赖在 LTS 上测试最充分。如果你用 nvm 管理版本直接nvm install --lts就行不要手动指定一个没发布的版本号。2.3 工具适配层的抽象逻辑openrig 最核心的设计是“工具适配层”。它不直接操作 Claude Code 或 Codex 的内部逻辑而是通过一个适配器接口把统一的模型描述转换成各工具的原生配置。这个思路类似于数据库驱动上层用统一的 SQL 接口下层由各数据库驱动负责翻译。适配器需要实现三个方法detect()检测工具是否安装、render(config)把统一配置渲染成工具原生格式、write(path)写入到正确位置。以 Claude Code 为例它的配置路径在 macOS/Linux 上是~/.claude/settings.jsonWindows 上是%USERPROFILE%\.claude\settings.json。Codex 的配置路径则取决于版本老版本用~/.codex/config.toml新版本可能支持~/.codex/config.yaml。openrig 的适配器会先探测这些路径如果目录不存在就创建如果文件已存在就备份后覆盖。这种设计的好处是当 Claude Code 或 Codex 升级后改了配置格式你只需要更新对应的适配器不需要动核心的 YAML 和渲染逻辑。坏处是适配器需要跟随工具版本维护如果工具更新频繁适配器可能滞后。我的经验是把适配器写成可插拔的独立文件每个工具一个.js文件放在adapters/目录下主脚本动态加载。这样即使某个适配器失效也不影响其他工具。2.4 与 cc switch 类方案的差异热词里出现了cc switch和cc switch local proxy failed while handling codex endpoint /responses。cc switch 是另一类方案它更偏向于“运行时切换”通过本地代理拦截请求动态把请求转发到不同端点。openrig 则偏向“配置时切换”在启动工具之前就把配置写好工具运行时直接连目标端点不经过额外代理。两种方案各有适用场景。cc switch 的优势是切换快不用重启工具适合频繁切换模型的场景。但它的缺点是引入了一个本地代理进程这个进程本身可能出问题比如local proxy failed while handling codex endpoint /responses就是代理在处理 Codex 的/responses端点时失败了。openrig 不引入额外进程配置写好后工具直连少一个故障点。代价是切换模型需要重新运行 openrig 渲染脚本并重启工具。我个人的选择是日常开发用 openrig因为配置稳定、故障少需要临时对比多个模型输出时才用 cc switch 这类代理方案。两者并不互斥你可以把 openrig 生成的配置作为 cc switch 的上游配置来源。3. 核心细节解析与实操要点3.1 openrig.yaml 的字段设计一份完整的openrig.yaml通常包含四个顶层字段version、models、tools、defaults。version用于标识配置格式版本方便后续做迁移。models定义所有可用的模型端点每个端点包含endpoint、api_key_env、model、timeout、max_tokens等字段。tools定义每个工具使用哪个模型作为默认、哪个作为回退。defaults定义全局默认值比如代理地址、重试次数、日志级别。这里重点说api_key_env字段。不要把 API Key 直接写在 YAML 里而是写环境变量名比如api_key_env: ANTHROPIC_API_KEY。openrig 渲染配置时会保留这个环境变量引用让工具自己去读取。这样做的好处是YAML 文件可以安全地提交到团队仓库每个人在自己的 shell 里设置不同的 Key。如果你用 direnv 或 dotenv可以在项目目录放一个.env文件openrig 启动时自动加载。timeout字段的单位是秒默认值建议设 60。但如果你用本地 LM Studio 跑大模型首次加载模型可能超过 60 秒这时候要把 timeout 调到 120 甚至 180。热词里有人问claude code 调用 lmstudio 的本地模型最常见的失败原因就是 timeout 太短请求还没返回就被工具掐断了。3.2 模型端点的兼容性处理不同模型供应商的 API 格式并不完全一致。官方 Claude 用/v1/messagesOpenAI 兼容端点用/v1/chat/completionsCodex 可能用/responses。openrig 在渲染配置时需要根据工具类型和端点类型做兼容处理。比如 Claude Code 连官方端点时配置里写api_format: anthropic连 LM Studio 时因为 LM Studio 提供 OpenAI 兼容接口配置里要写api_format: openai同时把端点地址指向http://127.0.0.1:1234/v1。这里有个容易踩的坑Codex 的/responses端点和 OpenAI 的/chat/completions端点参数不同。如果你把 Codex 指向一个只支持/chat/completions的第三方端点就会报the gpt-5.6-sol model is not supported when using codex或者local proxy failed while handling codex endpoint /responses。解决办法是在 openrig 的模型定义里加一个codex_compatible: true/false标记渲染 Codex 配置时如果端点不兼容就自动切换到回退模型或者提示用户手动指定一个兼容端点。我实测下来DeepSeek 和 GLM 的 OpenAI 兼容端点对 Codex 的支持比较好但需要在配置里显式指定model名称不能留空。LM Studio 的兼容性取决于你加载的模型和 LM Studio 版本较新版本对/responses的支持在逐步完善但如果你遇到 404 或 405先检查端点路径是否正确。3.3 环境变量与密钥管理openrig 本身不存储密钥它只负责把环境变量名渲染到工具配置里。这意味着你需要在 shell 启动文件.bashrc、.zshrc、PowerShell$PROFILE里导出这些变量。对于团队协作建议用一个.env.example文件列出所有需要的变量名每个人复制成.env后填入自己的值。如果你在 Windows 上用 PowerShell设置环境变量的语法和 bash 不同$env:ANTHROPIC_API_KEY sk-ant-xxxx $env:OPENAI_API_KEY sk-xxxx这些变量只在当前会话有效。要永久生效用[System.Environment]::SetEnvironmentVariable(ANTHROPIC_API_KEY, sk-ant-xxxx, User)。但注意永久设置后需要重启终端才能读取到。还有一个细节Claude Code 在某些版本里会检查ANTHROPIC_API_KEY和CLAUDE_CODE_USE_BEDROCK等变量。如果你同时设置了多个供应商的 KeyClaude Code 可能优先读取某一个。openrig 的defaults里可以加一个env_priority列表渲染时生成一个env.sh或env.ps1在启动工具前 source 一下确保优先级正确。3.4 配置文件路径的跨平台差异Claude Code 和 Codex 在不同操作系统上的配置路径不同这是 openrig 适配器需要处理的核心问题。下面这张表是我整理的实际路径对照工具macOS/LinuxWindowsClaude Code~/.claude/settings.json%USERPROFILE%\.claude\settings.jsonCodex (旧版)~/.codex/config.toml%USERPROFILE%\.codex\config.tomlCodex (新版)~/.codex/config.yaml%USERPROFILE%\.codex\config.yamlVS Code Claude 插件~/.vscode/extensions/下对应目录%USERPROFILE%\.vscode\extensions\openrig 的 Node.js 脚本用os.homedir()获取用户主目录然后用path.join()拼接路径这样在三个平台上都能正确工作。但要注意Windows 上有些工具会把配置写到%APPDATA%而不是%USERPROFILE%。如果你发现 openrig 写入了配置但工具没生效先用codex --help或claude --help看看工具自己报告的配置路径以工具输出为准。提示在 Windows 上运行 openrig 时建议用管理员权限打开终端否则某些目录可能没有写入权限。但不要用管理员权限运行 Claude Code 或 Codex 本身避免生成 root 所有的文件。4. 实操过程与核心环节实现4.1 环境准备Node.js 与包管理器第一步是安装 Node.js。去 Node.js 官网下载 LTS 版本或者用包管理器安装。macOS 上用brew install node22Ubuntu 上用curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -然后sudo apt install nodejs。Windows 上直接下载.msi安装包勾选“Add to PATH”。安装完成后验证node --version npm --version如果node --version输出v24.21.0但 npm 报错说明你装了一个不完整的版本。热词里的error installing 24.21.0: node.js v24.21.0 is not yet released就是因为有人手动指定了一个不存在的版本号。解决办法是卸载后重新安装 LTS 版本或者用 nvmnvm install --lts nvm use --ltsnvm 的好处是可以随时切换版本而且不会污染系统全局环境。如果你在 Ubuntu 上遇到权限问题不要用sudo npm install -g而是配置 npm 的全局目录到用户主目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH这样安装全局包就不需要 sudo 了。4.2 安装 Claude Code 与 Codex CLIClaude Code 的安装命令是npm install -g anthropic-ai/claude-code。安装完成后运行claude会进入交互式界面首次运行会引导你登录或设置 API Key。如果你在 Ubuntu 上遇到your organization has disabled claude subscription access for claude code说明你的账号类型不支持订阅访问需要改用 API Key 方式在环境变量里设置ANTHROPIC_API_KEY。Codex 的安装命令取决于你用的版本。官方 CLI 可以用npm install -g openai/codex安装后运行codex进入交互界面。如果你用的是第三方打包版本安装包可能是一个.exe或.dmg直接双击安装即可。安装完成后用codex --version验证。VS Code 用户还可以安装 Claude Code 插件在扩展市场搜索 “Claude Code” 即可。插件安装后需要在 VS Code 设置里配置claude-code.apiKey或指向 openrig 生成的配置文件。如果你同时用 CLI 和插件建议让 openrig 同时渲染两份配置保持行为一致。4.3 编写第一份 openrig.yaml下面是一份最小可用的openrig.yaml我把它放在项目根目录version: 1.0 models: claude_official: endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY model: claude-sonnet-4-20250514 api_format: anthropic timeout: 60 max_tokens: 8192 lmstudio_local: endpoint: http://127.0.0.1:1234/v1 api_key_env: LMSTUDIO_API_KEY model: qwen2.5-coder-7b-instruct api_format: openai timeout: 180 max_tokens: 4096 deepseek_api: endpoint: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY model: deepseek-coder api_format: openai timeout: 90 max_tokens: 8192 tools: claude_code: default_model: claude_official fallback_model: lmstudio_local config_path: ~/.claude/settings.json codex: default_model: deepseek_api fallback_model: lmstudio_local config_path: ~/.codex/config.yaml defaults: retry: 2 log_level: info proxy: 这份配置定义了三个模型、两个工具。Claude Code 默认走官方端点失败时回退到本地 LM Studio。Codex 默认走 DeepSeek失败时也回退到本地。proxy留空表示不走代理如果你在公司内网需要走 HTTP 代理填http://proxy.company.com:8080。4.4 运行渲染脚本并验证openrig 的渲染脚本入口通常是node openrig.js render或npx openrig render。运行后脚本会输出类似下面的日志[openrig] Loading config from ./openrig.yaml [openrig] Detected tools: claude_code, codex [openrig] Rendering claude_code config - ~/.claude/settings.json [openrig] Rendering codex config - ~/.codex/config.yaml [openrig] Done. 2 configs written, 0 errors.验证配置是否生效最直接的方法是启动工具并让它输出当前使用的模型。Claude Code 里可以用/model命令查看Codex 里可以用codex config show或类似命令。如果工具报错说找不到配置文件检查config_path里的~是否被正确展开。Node.js 的path.join不会自动展开~需要在脚本里用os.homedir()替换。我踩过的一个坑是Claude Code 在读取settings.json时如果文件里有它不认识的字段会直接报错退出而不是忽略。所以 openrig 渲染时要确保只写入 Claude Code 支持的字段。我的做法是维护一个字段白名单渲染前过滤掉不支持的字段。Codex 对未知字段的容忍度稍高但也会在日志里输出警告。4.5 接入本地 LM Studio 的完整流程本地模型接入是热词里问得最多的场景之一。完整流程如下下载并安装 LM Studio在“Discover”页面搜索并下载一个代码模型比如qwen2.5-coder-7b-instruct。在 LM Studio 的“Local Server”页面选择模型设置端口为1234点击“Start Server”。验证端点可用curl http://127.0.0.1:1234/v1/models应该返回模型列表。在openrig.yaml里添加lmstudio_local模型定义api_format设为openai。运行 openrig 渲染脚本把 Claude Code 或 Codex 的默认模型指向lmstudio_local。启动工具测试一个简单请求比如“写一个 Python 快速排序”。如果请求超时先把timeout调到 300 秒因为本地模型首次加载可能很慢。如果返回 404检查端点路径是/v1还是/v1/chat/completions不同 LM Studio 版本默认路径可能不同。如果返回 401检查LMSTUDIO_API_KEY是否设置LM Studio 默认不校验 Key但有些工具会强制要求非空随便填一个字符串即可。注意本地模型的能力和官方模型有差距不要指望 7B 模型能完成复杂的重构任务。我的经验是本地模型适合做代码补全、单元测试生成、简单 bug 修复复杂架构设计还是用官方模型。5. 常见问题与排查技巧实录5.1 配置类问题速查表下面这张表整理了我遇到过的配置类问题、原因和解决方法报错信息可能原因解决方法organization has disabled claude subscription access账号类型不支持订阅访问改用 API Key设置ANTHROPIC_API_KEYmodel is not supported when using codex端点不支持 Codex 的/responses格式换用兼容端点或在 openrig 里标记codex_compatible: falselocal proxy failed while handling codex endpoint /responses代理层无法处理 Codex 请求检查代理配置或绕过代理直连codex无法加载组织设置配置文件路径错误或权限不足用codex --help确认配置路径检查文件权限error installing 24.21.0: node.js v24.21.0 is not yet released指定了不存在的 Node.js 版本改用 LTS 版本nvm install --ltsyaml文件解析失败缩进错误或特殊字符未转义用 VS Code YAML 插件校验检查冒号后的空格5.2 网络与端点连通性排查配置写对了但请求还是失败大概率是网络问题。排查顺序如下第一步用curl直接测试端点。比如测试 DeepSeekcurl -X POST https://api.deepseek.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-coder,messages:[{role:user,content:hi}]}如果 curl 能通但工具不通说明问题在工具配置层。如果 curl 也不通说明是网络层问题检查 DNS、防火墙、代理设置。第二步检查环境变量是否在当前 shell 生效。echo $ANTHROPIC_API_KEY应该输出你的 Key。如果为空说明变量没导出或者你在错误的 shell 里运行。第三步检查工具是否读取了正确的配置文件。Claude Code 可以用claude config list查看当前配置Codex 可以用codex config show。如果工具显示的配置和 openrig 生成的不一致说明工具读了另一个路径的文件用straceLinux或Process MonitorWindows追踪文件读取。5.3 版本兼容性与升级策略Claude Code 和 Codex 都在快速迭代配置格式可能随版本变化。我的策略是锁定一个已知可用的版本不要盲目升级。在package.json里固定版本号比如anthropic-ai/claude-code: 1.0.24而不是用^1.0.24。升级前先在测试环境验证 openrig 渲染的配置是否兼容新版本。如果升级后工具报配置错误先回滚到旧版本然后查看新版本的 release notes看配置格式是否有 breaking change。openrig 的适配器应该针对每个工具版本维护一个映射表比如claude_code1.0.x用一套渲染逻辑claude_code1.1.x用另一套。这样即使工具升级也不会影响旧版本用户。5.4 实操心得与避坑建议第一条心得不要把 API Key 写在 YAML 里也不要把.env文件提交到 Git。用.gitignore忽略.env只提交.env.example。团队协作时用密钥管理服务如 1Password、Vault分发 Key而不是在聊天群里发。第二条心得openrig 渲染配置前先备份原配置。我的脚本里加了一个--backup参数每次渲染前把原文件复制到~/.openrig/backups/下带时间戳。这样即使渲染出错也能快速恢复。第三条心得如果你同时用 Claude Code 的 CLI 和 VS Code 插件确保两者读取同一份配置。VS Code 插件有时会用自己的配置存储不读~/.claude/settings.json。解决办法是在 VS Code 设置里显式指定claude-code.configPath指向 openrig 生成的配置文件。第四条心得本地模型端点不要用localhost用127.0.0.1。在某些系统上localhost会解析到 IPv6 地址::1而 LM Studio 可能只监听 IPv4。用127.0.0.1可以避免这个解析问题。第五条心得如果你在公司内网代理设置要区分 HTTP 和 HTTPS。有些代理只支持 HTTP 转发HTTPS 请求需要 CONNECT 方法。在 openrig 的defaults.proxy里填代理地址后还要在工具配置里设置NODE_TLS_REJECT_UNAUTHORIZED0仅限内网自签名证书场景否则 TLS 握手会失败。但注意这个设置会降低安全性只在可信内网使用。5.5 扩展方向从单机到团队协作openrig 目前的设计是单机配置管理但很容易扩展到团队场景。思路是把openrig.yaml拆成两层一层是团队共享的base.yaml定义模型端点和工具适配器另一层是个人override.yaml定义个人的 API Key 环境变量名和偏好设置。渲染时用lodash.merge合并两层配置个人配置优先。这样团队可以统一管理模型端点个人只需要维护自己的 Key。新成员加入时克隆仓库复制override.example.yaml为override.yaml填入自己的 Key运行openrig render即可。整个过程不超过五分钟。另一个扩展方向是加一个openrig doctor命令自动检查环境Node.js 版本、工具是否安装、配置文件是否存在、端点是否连通、环境变量是否设置。输出一个检查报告标出有问题的项。这个命令在排查问题时特别有用比手动一步步检查快得多。6. 关于 openrig 后续维护的一些个人看法我用 openrig 这套思路管理 AI 编程工具配置已经有一段时间了最大的感受是配置管理这件事越早标准化越好。一开始手动改两三个文件觉得没什么等到工具数量增加到四五个、模型端点增加到七八个的时候手动改配置就成了负担而且容易出错。openrig 的价值不在于它有多复杂而在于它把“配置”这件事从“手工活”变成了“可版本控制、可复现、可协作”的工程实践。如果你现在只用一个工具、一个模型可能觉得没必要引入 openrig。但我的建议是即使现在用不上也可以先把配置结构设计好用 YAML 管理起来。等到需要切换模型或增加工具时你会发现前期这点投入省下了大量折腾时间。最后分享一个小技巧在openrig.yaml里加一个notes字段记录每个模型端点的申请日期、额度、到期时间。这样每次打开配置文件就能看到哪些 Key 快过期了提前续期避免突然断供影响开发。这个字段 openrig 渲染时会忽略纯粹是给人看的但非常实用。