1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里常指设备支架、钻井平台这类实体结构。翻了翻社区讨论和几个仓库的 README 才反应过来这里的 rig 更接近装配台的意思——把散落各处的 AI 编码工具、模型接口、本地配置像搭积木一样组装到一套统一的运行环境里。openrig 的核心定位就是给 Claude Code、Codex 这类命令行 AI 编码助手做一层开箱即用的配置编排层用 YAML 描述环境用 Node.js 做运行时底座把原本需要手动折腾半天的安装、切换、代理转发、模型接入这些事收敛成几条命令。它解决的问题其实很具体。现在用 AI 辅助写代码的人越来越多但工具链碎得厉害Claude Code 有自己的安装方式和配置目录Codex 又是另一套想接本地模型比如 LM Studio 或者第三方 API 还得改环境变量、配代理、处理端点路径。更麻烦的是多工具共存的时候配置互相打架今天 Claude Code 能用明天 Codex 报错排查起来全靠翻日志。openrig 想做的就是把这些工具的配置抽象成声明式的 YAML 文件你描述我要什么它负责怎么装怎么连切换工具或者换模型的时候改几行配置就行不用重装。适合谁来参考这份内容三类人最对口。第一类是刚接触 Claude Code 或 Codex、被安装步骤和网络配置卡住的新手openrig 能帮你跳过大量试错。第二类是同时用多个 AI 编码工具的老手需要一套统一的配置管理方案避免环境互相污染。第三类是想把 AI 编码能力集成到自己工作流里的开发者openrig 的 YAML 驱动思路很适合做二次封装。哪怕你最后不用 openrig它背后这套YAML 声明配置 Node.js 运行时 端点转发的组合拳思路也值得单独拆出来学。我下面会从设计思路、核心细节、实操流程、问题排查四个层面把 openrig 拆开讲中间会穿插 Claude Code、Codex、YAML、Node.js 这些关键词的实际用法。内容基于社区常见实践和我自己踩过的坑整理具体版本和参数请以你拿到的实际仓库为准。2. 整体设计与思路拆解2.1 为什么用 YAML 做配置层而不是 JSON 或 TOMLopenrig 选 YAML 作为配置描述语言这个决定背后有很实际的考量。JSON 的问题是写起来太啰嗦一个嵌套三层的配置全是花括号和引号人眼扫过去很累而且 JSON 不支持注释你想在配置里标注这行是接本地模型的都没地方写。TOML 虽然支持注释、结构也清晰但它在表达嵌套数组和复杂对象的时候比较别扭尤其是配置里要描述多个工具、每个工具下面又有多个模型端点这种层级结构TOML 的[[table]]语法写多了容易晕。YAML 的优势在于缩进即层级天然适合表达树状配置而且支持注释、支持多行字符串、支持锚点和引用。openrig 的配置里经常要写端点 URL、API Key 占位符、模型名称、启动参数这些东西用 YAML 写出来可读性明显更好。举个典型片段tools: claude-code: enabled: true endpoint: http://127.0.0.1:8080/v1 model: claude-sonnet env: ANTHROPIC_BASE_URL: ${CLAUDE_ENDPOINT} codex: enabled: true endpoint: http://127.0.0.1:8080/v1/responses model: gpt-5.6-sol这种结构一眼就能看出哪个工具启用、连哪个端点、用什么模型。换成 JSON 你得数括号换成 TOML 你得在[tools.claude-code]和[tools.codex]之间来回跳。YAML 的锚点功能还能复用公共配置比如多个工具共用同一个本地端点可以定义一次然后: *common引用减少重复。注意YAML 对缩进极其敏感Tab 和空格混用会直接报解析错误。openrig 的配置文件统一用两个空格缩进别用 Tab这是新手最容易翻车的地方。2.2 Node.js 作为运行时的取舍openrig 跑在 Node.js 上这个选择在 AI 工具圈子里很常见原因有几个。Claude Code 和 Codex 的 CLI 本身就是 Node.js 生态的产物用 npm 全局安装运行时天然共享同一套环境不需要额外装 Python 或者 Go 的运行时。Node.js 的跨平台支持也成熟Windows、macOS、Linux 上装法基本一致openrig 想做到一套配置三平台通用Node.js 是最省事的地基。另一个关键点是 Node.js 的异步 IO 模型适合做代理转发。openrig 在中间要处理请求转发、端点重写、流式响应透传这些事Node.js 的http模块和流处理能力做这个很顺手。你如果看过 openrig 的源码会发现它内部起了一个本地 HTTP 服务把 Claude Code 或 Codex 发过来的请求按 YAML 里定义的规则转发到真正的模型端点同时处理路径重写和头部注入。这个本地代理的角色用 Node.js 实现代码量不大但很稳。版本选择上有个坑要提前说。Node.js 的版本迭代很快有些新版本刚发布时 npm 上的包还没跟上会出现error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错。稳妥的做法是用 LTS 版本比如 20.x 或 22.x 的 LTS去 Node.js 官网下载页选 LTS 那一栏别追最新的 Current 版本。装完之后node -v和npm -v都确认一下版本对不上后面全是连锁问题。2.3 端点转发与多工具共存的架构openrig 最核心的设计是本地端点 配置路由。它不直接改 Claude Code 或 Codex 的源码而是在本地起一个服务让这些工具把请求发到本地端点openrig 再根据 YAML 配置决定转发到哪。这样做的好处是工具本身无感知你随时可以改配置切换后端模型不用动工具的任何文件。这个架构解决了一个很现实的痛点Claude Code 和 Codex 的端点格式不完全一样。Claude Code 走的是 Anthropic 风格的/v1/messagesCodex 走的是 OpenAI 风格的/v1/responses。如果你想让它们共用同一个本地模型服务端点路径和请求体格式都得适配。openrig 在中间做了一层转换YAML 里分别配置每个工具的端点它负责把请求路由到正确的地方。社区里那个cc switch local proxy failed while handling codex endpoint /responses的报错本质就是端点路径没配对Codex 发的/responses请求没被正确转发。多工具共存还有个配置隔离的问题。Claude Code 默认读~/.claude目录下的配置Codex 读自己的配置目录两者如果都指向同一个本地端点但用了不同的 API Key 或者模型名很容易串。openrig 的做法是在 YAML 里给每个工具独立的配置块启动时分别注入对应的环境变量工具之间互不干扰。这个思路值得借鉴哪怕你不用 openrig自己管理多工具的时候也应该按工具分配置文件别全塞一个.env里。3. 核心细节解析与实操要点3.1 YAML 配置文件的结构与关键字段openrig 的 YAML 配置一般分三大块全局设置、工具定义、模型端点。全局设置管日志级别、监听端口、默认超时这些工具定义描述每个 AI 编码工具怎么启动、读哪个环境变量模型端点定义后端服务的地址、密钥、模型名。下面是一个相对完整的结构示例global: port: 8080 log_level: info timeout: 120 endpoints: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: lm-studio models: - qwen2.5-coder - deepseek-coder remote-api: base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} models: - gpt-5.6-sol tools: claude-code: enabled: true endpoint: local-lmstudio model: qwen2.5-coder extra_env: ANTHROPIC_BASE_URL: http://127.0.0.1:8080 codex: enabled: true endpoint: remote-api model: gpt-5.6-sol extra_env: OPENAI_BASE_URL: http://127.0.0.1:8080/v1几个字段值得单独说。base_url是后端服务的真实地址本地模型一般是127.0.0.1加端口远程 API 就是服务商给的地址。api_key支持${VAR}语法从环境变量读取这样密钥不用写死在文件里避免提交到仓库泄露。models是个列表openrig 启动时会校验你指定的模型名在不在这个列表里不在就报错能提前发现拼写问题。tools下面的endpoint字段引用的是上面endpoints里定义的键名这是一种引用式配置改后端地址只需要改一处。extra_env是注入给工具进程的环境变量Claude Code 认ANTHROPIC_BASE_URLCodex 认OPENAI_BASE_URL这两个变量指向 openrig 的本地监听地址工具就会把请求发给 openrig 而不是直连后端。提示api_key用${VAR}引用环境变量时确保启动 openrig 的 shell 里这个变量已经 export 了否则会解析成空字符串请求到后端直接 401。3.2 Claude Code 与 Codex 的端点差异处理Claude Code 和 Codex 虽然都是 AI 编码 CLI但它们的 API 协议不一样这是 openrig 配置里最容易出错的地方。Claude Code 遵循 Anthropic 的 Messages API请求路径是/v1/messages请求体里messages数组的角色是user和assistant系统提示单独放在system字段。Codex 遵循 OpenAI 的 Responses API路径是/v1/responses请求体结构不同工具调用和流式响应的格式也有差异。openrig 在转发的时候要处理这个差异。如果后端是原生支持 Anthropic 协议的服务Claude Code 的请求可以直接透传如果后端只支持 OpenAI 协议openrig 就得做协议转换把 Messages 格式转成 Responses 格式。反过来 Codex 接 Anthropic 风格的后端也一样。这个转换逻辑是 openrig 的核心价值之一但也是最容易出 bug 的地方。实际操作中我建议先确认后端服务支持哪种协议。本地跑 LM Studio 的话它同时提供 OpenAI 兼容端点和部分 Anthropic 兼容端点但路径和字段支持程度不一样。你可以先用 curl 手动测一下curl http://127.0.0.1:1234/v1/models能列出模型说明 OpenAI 兼容端点通了。再测 Anthropic 风格curl http://127.0.0.1:1234/v1/messages \ -H Content-Type: application/json \ -d {model:qwen2.5-coder,max_tokens:100,messages:[{role:user,content:hi}]}如果这个返回正常Claude Code 接这个端点问题不大。如果报 404 或者格式错误说明后端不支持 Anthropic 协议得靠 openrig 做转换或者换一个支持的后端。Codex 那边同理先测/v1/responses端点。社区里the gpt-5.6-sol model is not supported when using codex with a...这类报错往往是模型名和后端实际提供的模型对不上或者 Codex 的配置里模型名写错了。排查的时候先确认后端/v1/models返回的列表里有没有你写的那个名字大小写、连字符都要对。3.3 环境变量注入与配置隔离openrig 启动工具进程的时候环境变量的注入顺序和覆盖规则很关键。一般来说openrig 会先继承当前 shell 的环境变量然后叠加 YAML 里extra_env定义的值最后再注入一些运行时生成的变量比如本地端点地址。这个顺序意味着extra_env里的值会覆盖 shell 里同名的变量这是符合预期的因为 YAML 配置应该优先。但这里有个坑Claude Code 和 Codex 可能读同一个环境变量名但期望不同的值。比如某些版本里两者都读OPENAI_API_KEY但一个要的是本地模型的占位 key另一个要的是远程 API 的真实 key。如果两个工具同时启用环境变量就会打架。openrig 的解法是给每个工具启动独立的子进程子进程的环境变量互相隔离不共享。你自己手动配置的时候也要注意这点别在一个 shell 里同时 export 两个工具需要的冲突变量。配置隔离还体现在配置目录上。Claude Code 默认读~/.claude/settings.json或者项目目录下的.claude文件夹Codex 读自己的配置路径。openrig 一般不改这些默认路径而是通过环境变量把端点指向本地工具的其他配置还是走自己的目录。这样你原来的 Claude Code 配置、快捷键、历史记录都不受影响只是请求走了 openrig 的转发。注意如果你之前手动改过 Claude Code 的ANTHROPIC_BASE_URL指向别的地址启用 openrig 前先把这个变量清掉或者注释掉否则 openrig 注入的值可能被旧值覆盖请求发到了错误的地方。4. 实操过程与核心环节实现4.1 从零搭建 openrig 运行环境假设你是一台干净的机器什么都没装完整流程是这样的。第一步装 Node.js去官网下载 LTS 版本Windows 下直接下.msi安装包双击macOS 用.pkg或者 HomebrewLinux 用包管理器或者 nvm。装完验证node -v npm -v两个命令都能输出版本号就说明装好了。如果node -v报 command not found检查 PATH 有没有配好Windows 下重开一个终端试试环境变量刷新需要新会话。第二步装 openrig。如果它发布在 npm 上直接全局安装npm install -g openrig如果是从源码跑先 clone 仓库再装依赖git clone openrig-repo cd openrig npm install npm run build第三步准备 YAML 配置文件。在项目目录或者用户目录下建一个openrig.yaml按上一节的结构填好你的端点和工具配置。第一次配建议只启用一个工具比如先只配 Claude Code跑通了再加 Codex减少变量。第四步启动 openrigopenrig start --config ./openrig.yaml启动后它会监听 YAML 里配的端口默认 8080。看到日志里打出listening on 127.0.0.1:8080就说明起来了。这时候另开一个终端启动 Claude Code它会读环境变量里的ANTHROPIC_BASE_URL如果 openrig 注入成功请求就会走本地转发。4.2 接入本地模型 LM Studio 的完整配置LM Studio 是本地跑模型比较省心的选择图形界面下载模型、一键启动服务。它默认监听1234端口提供 OpenAI 兼容端点。openrig 接 LM Studio 的配置重点在端点地址和模型名要对上。先在 LM Studio 里加载一个编码能力强的模型比如 Qwen2.5-Coder 或者 DeepSeek-Coder启动本地服务确认http://127.0.0.1:1234/v1/models能返回模型列表。然后在 openrig 的 YAML 里这样配endpoints: lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: lm-studio models: - qwen2.5-coder-7b-instruct tools: claude-code: enabled: true endpoint: lmstudio model: qwen2.5-coder-7b-instruct extra_env: ANTHROPIC_BASE_URL: http://127.0.0.1:8080 ANTHROPIC_API_KEY: lm-studio这里ANTHROPIC_API_KEY填lm-studio是占位LM Studio 不校验 key但 Claude Code 要求这个变量存在不填会报错。模型名必须和 LM Studio 里加载的模型标识完全一致去/v1/models的返回里复制别手打。启动 openrig 后再启动 Claude Code发一条测试消息看 openrig 的日志里有没有转发记录。如果日志显示请求进来了但转发失败多半是模型名不对或者 LM Studio 那边模型没加载好。如果 Claude Code 直接报连接错误检查ANTHROPIC_BASE_URL是不是真的指向了 openrig 的端口。4.3 Codex 接入第三方 API 的配置要点Codex 接第三方 API 的配置和 Claude Code 类似但端点路径要注意。Codex 走/v1/responses如果你的第三方 API 只提供/v1/chat/completions就需要 openrig 做路径重写。YAML 里可以配一个路径映射endpoints: thirdparty: base_url: https://api.example.com/v1 api_key: ${THIRD_PARTY_KEY} path_rewrite: /v1/responses: /v1/chat/completions models: - gpt-5.6-sol tools: codex: enabled: true endpoint: thirdparty model: gpt-5.6-sol extra_env: OPENAI_BASE_URL: http://127.0.0.1:8080/v1 OPENAI_API_KEY: ${THIRD_PARTY_KEY}path_rewrite把 Codex 发的/v1/responses重写成后端支持的/v1/chat/completions。但要注意路径重写只是改了 URL请求体格式如果不一样还是会有问题。Responses API 和 Chat Completions API 的请求体结构有差异openrig 如果支持请求体转换会在转发时做映射如果不支持你可能得换一个原生支持 Responses API 的后端。第三方 API 的 key 用环境变量引用启动 openrig 前先 exportexport THIRD_PARTY_KEYyour-key-here openrig start --config ./openrig.yamlWindows 下用set THIRD_PARTY_KEYyour-key-here或者 PowerShell 的$env:THIRD_PARTY_KEYyour-key-here。key 别写进 YAML 提交到仓库这是基本的安全习惯。4.4 多工具切换与配置热更新openrig 的一个实用功能是配置热更新改完 YAML 不用重启整个服务它重新加载配置就行。这对多工具切换场景很有用你上午用 Claude Code 接本地模型写代码下午想换成 Codex 接远程 API改几行 YAML 触发重载两个工具的环境变量就切换了。热更新的触发方式一般有两种一种是发信号比如kill -HUP pid另一种是 openrig 监听配置文件变化自动重载。具体支持哪种看你的版本。手动重载的话openrig reload或者找到 openrig 的进程 ID 发信号。重载后确认日志里打出config reloaded之类的提示再验证工具是否连到了新端点。多工具同时启用的时候注意端口别冲突。openrig 自己占一个端口Claude Code 和 Codex 各自可能也有本地端口需求YAML 里配的监听端口要错开。另外两个工具同时跑会争抢本地模型的推理资源本地模型一般并发能力有限建议一次只开一个工具或者给本地模型服务配好并发队列。提示热更新虽然方便但涉及端点地址变更的时候已经建立的连接不会自动断开重连。改完配置后最好把工具进程也重启一下确保新配置完全生效。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解决安装阶段最常见的就是 Node.js 版本问题。error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个报错通常是你用的某个工具或者 npm 包指定了 Node.js 版本但那个版本还没正式发布或者你的镜像源里没有。解决办法是降到 LTS 版本去 Node.js 官网下载页选 LTS别用 Current。如果你用 nvm 管理版本nvm install --lts nvm use --lts另一个常见问题是 npm 全局安装权限不足Linux 和 macOS 下不加 sudo 会报EACCES。但我不建议直接sudo npm install -g那样装出来的包权限是 root后面更新和卸载都麻烦。正确做法是配置 npm 的全局目录到用户目录npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH然后重新npm install -g openrig不用 sudo 也能装。Windows 下如果遇到codex安装 windows桌面版相关的报错检查是不是装了多个 Node.js 版本导致 PATH 混乱。用where node看看有几个路径清理掉多余的只留一个 LTS 版本。5.2 端点转发失败的排查思路cc switch local proxy failed while handling codex endpoint /responses这类报错排查要按链路一步步来。先确认 openrig 服务本身活着curl http://127.0.0.1:8080/health或者看日志有没有监听成功。然后确认后端服务活着直接 curl 后端端点看能不能通。两头都通但转发失败问题就在 openrig 的配置上。检查 YAML 里 Codex 的端点路径配置。Codex 发的是/v1/responsesopenrig 转发的时候有没有正确匹配到这个路径。如果 YAML 里配的base_url是http://127.0.0.1:1234/v1openrig 拼接后的完整路径应该是http://127.0.0.1:1234/v1/responses确认后端真的在这个路径上提供服务。有些后端只提供/v1/chat/completions那就得配path_rewrite。再看请求头。Codex 发的请求带Authorization: Bearer keyopenrig 转发的时候有没有把这个头带上或者有没有用 YAML 里配的 key 覆盖。如果后端要求特定的头比如anthropic-versionopenrig 得注入。这些细节在 YAML 里一般有对应的配置项翻一下文档。5.3 模型不支持的报错处理the gpt-5.6-sol model is not supported when using codex with a...这个报错很直白就是模型名对不上。先去后端/v1/models拿准确列表把模型名复制过来。注意有些后端返回的模型名带版本后缀或者组织前缀比如openai/gpt-5.6-sol或者gpt-5.6-sol-20250101你 YAML 里写的必须和返回的完全一致。还有一种情况是后端支持这个模型但 Codex 的配置里模型名被别的地方覆盖了。检查环境变量里有没有OPENAI_MODEL或者类似的变量它的优先级可能高于 YAML 配置。清掉这些变量再试。如果模型名确认没错还是报不支持可能是协议不匹配。Codex 用 Responses API 发请求后端只支持 Chat Completions模型虽然存在但接口不认。这时候要么换支持 Responses API 的后端要么靠 openrig 做协议转换要么把 Codex 的端点指向一个兼容层。5.4 常见问题速查表报错关键词可能原因排查动作node.js vXX not yet releasedNode.js 版本过新或镜像源缺失降到 LTS 版本换官方源EACCES permission deniednpm 全局目录权限不足配置 npm prefix 到用户目录proxy failed handling endpoint端点路径不匹配或后端未启动分别 curl 前后端检查 path_rewritemodel is not supported模型名错误或协议不匹配核对 /v1/models 列表检查协议401 UnauthorizedAPI Key 未注入或为空检查环境变量是否 exportYAML 引用是否正确connection refusedopenrig 或后端未监听确认端口检查防火墙config parse errorYAML 缩进或语法错误用 YAML 校验工具检查统一用空格5.5 我踩过的几个坑第一个坑是 YAML 里的布尔值。YAML 会把yes、no、on、off解析成布尔值如果你某个字段想写字符串on不加引号就变成true了。openrig 配置里enabled字段是布尔值没问题但如果有别的字段期望字符串记得加引号。第二个坑是环境变量里的路径。Windows 下路径带反斜杠YAML 里写的时候要么用正斜杠要么用双引号包起来否则反斜杠会被当转义符。比如C:\Users\name在 YAML 里可能被解析成奇怪的东西写成C:/Users/name或者C:\\Users\\name更稳。第三个坑是端口占用。openrig 默认 8080但 8080 经常被别的开发服务占了。启动前用netstat -ano | findstr 8080Windows或者lsof -i :8080macOS/Linux查一下占了就换端口YAML 里改global.port就行。第四个坑是本地模型的上下文长度。本地跑的模型上下文窗口往往比云端小Claude Code 或者 Codex 发过去的请求可能超出窗口后端直接报错。这种情况要么换上下文更大的模型要么在 openrig 里配请求截断要么在工具侧限制发送的上下文量。6. 配置扩展与工作流集成6.1 把 openrig 配置纳入版本管理openrig 的 YAML 配置适合纳入 Git 管理但密钥不能提交。做法是把配置拆成两部分openrig.yaml放结构化的非敏感配置openrig.local.yaml放密钥和本地路径后者加到.gitignore里。openrig 启动时支持配置合并先读主配置再读本地覆盖openrig start --config ./openrig.yaml --override ./openrig.local.yaml这样团队协作的时候主配置可以共享每个人根据自己的环境写本地覆盖文件。密钥用环境变量引用本地文件里只写变量名不写值值放在 shell 的 profile 里或者用密钥管理工具注入。6.2 与 VS Code 的配合使用很多人用 Claude Code 或 Codex 是在 VS Code 的集成终端里openrig 的配置对这种方式同样有效。VS Code 的终端继承系统的环境变量只要 openrig 注入的环境变量在终端里可见Claude Code 的 VS Code 扩展或者终端里的 CLI 都能走 openrig 转发。如果你用claude code for vs code这个扩展注意扩展可能有自己的配置入口检查扩展设置里有没有覆盖ANTHROPIC_BASE_URL。有的话改成 openrig 的地址或者清空让它读环境变量。VS Code 的settings.json里也可以配终端的环境变量{ terminal.integrated.env.linux: { ANTHROPIC_BASE_URL: http://127.0.0.1:8080 } }Windows 下把linux换成windowsmacOS 换成osx。这样每次开终端自动带上变量不用手动 export。6.3 后续可以扩展的方向openrig 这套 YAML 驱动的思路可以往外延伸不少。比如加一个配置模板功能预置几套常用组合——本地模型开发模式、远程 API 生产模式、混合模式切换的时候直接选模板不用手改 YAML。再比如加健康检查openrig 定期探测后端端点挂了自动切换到备用端点提高可用性。还可以做配置校验启动前用 JSON Schema 校验 YAML 的结构和字段类型把拼写错误、类型错误提前拦下来而不是等到运行时才报错。这个对新手特别友好能省掉大量排查时间。如果你想把 openrig 集成到 CI 或者自动化脚本里它的 CLI 接口可以进一步封装比如提供openrig test命令自动跑一遍端点连通性测试输出每个工具每个端点的状态报告。这样部署前跑一下心里有底。我个人在实际操作中的体会是openrig 这类工具的价值不在于它做了多复杂的事而在于它把原本散落各处的配置收敛到了一处用声明式的方式管理。你花半小时把 YAML 配好后面切换工具、换模型、加新端点都是改几行配置的事不用再翻每个工具的文档重新折腾。这个投入产出比在长期使用中会越来越明显。最后再分享一个小技巧把常用的 curl 测试命令写成 shell 脚本每次改完配置跑一遍比在工具里试错快得多也更容易定位问题出在哪一层。 openrig 配置编排：YAML 驱动 Claude Code 与 Codex 多工具共存
1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里常指设备支架、钻井平台这类实体结构。翻了翻社区讨论和几个仓库的 README 才反应过来这里的 rig 更接近装配台的意思——把散落各处的 AI 编码工具、模型接口、本地配置像搭积木一样组装到一套统一的运行环境里。openrig 的核心定位就是给 Claude Code、Codex 这类命令行 AI 编码助手做一层开箱即用的配置编排层用 YAML 描述环境用 Node.js 做运行时底座把原本需要手动折腾半天的安装、切换、代理转发、模型接入这些事收敛成几条命令。它解决的问题其实很具体。现在用 AI 辅助写代码的人越来越多但工具链碎得厉害Claude Code 有自己的安装方式和配置目录Codex 又是另一套想接本地模型比如 LM Studio 或者第三方 API 还得改环境变量、配代理、处理端点路径。更麻烦的是多工具共存的时候配置互相打架今天 Claude Code 能用明天 Codex 报错排查起来全靠翻日志。openrig 想做的就是把这些工具的配置抽象成声明式的 YAML 文件你描述我要什么它负责怎么装怎么连切换工具或者换模型的时候改几行配置就行不用重装。适合谁来参考这份内容三类人最对口。第一类是刚接触 Claude Code 或 Codex、被安装步骤和网络配置卡住的新手openrig 能帮你跳过大量试错。第二类是同时用多个 AI 编码工具的老手需要一套统一的配置管理方案避免环境互相污染。第三类是想把 AI 编码能力集成到自己工作流里的开发者openrig 的 YAML 驱动思路很适合做二次封装。哪怕你最后不用 openrig它背后这套YAML 声明配置 Node.js 运行时 端点转发的组合拳思路也值得单独拆出来学。我下面会从设计思路、核心细节、实操流程、问题排查四个层面把 openrig 拆开讲中间会穿插 Claude Code、Codex、YAML、Node.js 这些关键词的实际用法。内容基于社区常见实践和我自己踩过的坑整理具体版本和参数请以你拿到的实际仓库为准。2. 整体设计与思路拆解2.1 为什么用 YAML 做配置层而不是 JSON 或 TOMLopenrig 选 YAML 作为配置描述语言这个决定背后有很实际的考量。JSON 的问题是写起来太啰嗦一个嵌套三层的配置全是花括号和引号人眼扫过去很累而且 JSON 不支持注释你想在配置里标注这行是接本地模型的都没地方写。TOML 虽然支持注释、结构也清晰但它在表达嵌套数组和复杂对象的时候比较别扭尤其是配置里要描述多个工具、每个工具下面又有多个模型端点这种层级结构TOML 的[[table]]语法写多了容易晕。YAML 的优势在于缩进即层级天然适合表达树状配置而且支持注释、支持多行字符串、支持锚点和引用。openrig 的配置里经常要写端点 URL、API Key 占位符、模型名称、启动参数这些东西用 YAML 写出来可读性明显更好。举个典型片段tools: claude-code: enabled: true endpoint: http://127.0.0.1:8080/v1 model: claude-sonnet env: ANTHROPIC_BASE_URL: ${CLAUDE_ENDPOINT} codex: enabled: true endpoint: http://127.0.0.1:8080/v1/responses model: gpt-5.6-sol这种结构一眼就能看出哪个工具启用、连哪个端点、用什么模型。换成 JSON 你得数括号换成 TOML 你得在[tools.claude-code]和[tools.codex]之间来回跳。YAML 的锚点功能还能复用公共配置比如多个工具共用同一个本地端点可以定义一次然后: *common引用减少重复。注意YAML 对缩进极其敏感Tab 和空格混用会直接报解析错误。openrig 的配置文件统一用两个空格缩进别用 Tab这是新手最容易翻车的地方。2.2 Node.js 作为运行时的取舍openrig 跑在 Node.js 上这个选择在 AI 工具圈子里很常见原因有几个。Claude Code 和 Codex 的 CLI 本身就是 Node.js 生态的产物用 npm 全局安装运行时天然共享同一套环境不需要额外装 Python 或者 Go 的运行时。Node.js 的跨平台支持也成熟Windows、macOS、Linux 上装法基本一致openrig 想做到一套配置三平台通用Node.js 是最省事的地基。另一个关键点是 Node.js 的异步 IO 模型适合做代理转发。openrig 在中间要处理请求转发、端点重写、流式响应透传这些事Node.js 的http模块和流处理能力做这个很顺手。你如果看过 openrig 的源码会发现它内部起了一个本地 HTTP 服务把 Claude Code 或 Codex 发过来的请求按 YAML 里定义的规则转发到真正的模型端点同时处理路径重写和头部注入。这个本地代理的角色用 Node.js 实现代码量不大但很稳。版本选择上有个坑要提前说。Node.js 的版本迭代很快有些新版本刚发布时 npm 上的包还没跟上会出现error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错。稳妥的做法是用 LTS 版本比如 20.x 或 22.x 的 LTS去 Node.js 官网下载页选 LTS 那一栏别追最新的 Current 版本。装完之后node -v和npm -v都确认一下版本对不上后面全是连锁问题。2.3 端点转发与多工具共存的架构openrig 最核心的设计是本地端点 配置路由。它不直接改 Claude Code 或 Codex 的源码而是在本地起一个服务让这些工具把请求发到本地端点openrig 再根据 YAML 配置决定转发到哪。这样做的好处是工具本身无感知你随时可以改配置切换后端模型不用动工具的任何文件。这个架构解决了一个很现实的痛点Claude Code 和 Codex 的端点格式不完全一样。Claude Code 走的是 Anthropic 风格的/v1/messagesCodex 走的是 OpenAI 风格的/v1/responses。如果你想让它们共用同一个本地模型服务端点路径和请求体格式都得适配。openrig 在中间做了一层转换YAML 里分别配置每个工具的端点它负责把请求路由到正确的地方。社区里那个cc switch local proxy failed while handling codex endpoint /responses的报错本质就是端点路径没配对Codex 发的/responses请求没被正确转发。多工具共存还有个配置隔离的问题。Claude Code 默认读~/.claude目录下的配置Codex 读自己的配置目录两者如果都指向同一个本地端点但用了不同的 API Key 或者模型名很容易串。openrig 的做法是在 YAML 里给每个工具独立的配置块启动时分别注入对应的环境变量工具之间互不干扰。这个思路值得借鉴哪怕你不用 openrig自己管理多工具的时候也应该按工具分配置文件别全塞一个.env里。3. 核心细节解析与实操要点3.1 YAML 配置文件的结构与关键字段openrig 的 YAML 配置一般分三大块全局设置、工具定义、模型端点。全局设置管日志级别、监听端口、默认超时这些工具定义描述每个 AI 编码工具怎么启动、读哪个环境变量模型端点定义后端服务的地址、密钥、模型名。下面是一个相对完整的结构示例global: port: 8080 log_level: info timeout: 120 endpoints: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: lm-studio models: - qwen2.5-coder - deepseek-coder remote-api: base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} models: - gpt-5.6-sol tools: claude-code: enabled: true endpoint: local-lmstudio model: qwen2.5-coder extra_env: ANTHROPIC_BASE_URL: http://127.0.0.1:8080 codex: enabled: true endpoint: remote-api model: gpt-5.6-sol extra_env: OPENAI_BASE_URL: http://127.0.0.1:8080/v1几个字段值得单独说。base_url是后端服务的真实地址本地模型一般是127.0.0.1加端口远程 API 就是服务商给的地址。api_key支持${VAR}语法从环境变量读取这样密钥不用写死在文件里避免提交到仓库泄露。models是个列表openrig 启动时会校验你指定的模型名在不在这个列表里不在就报错能提前发现拼写问题。tools下面的endpoint字段引用的是上面endpoints里定义的键名这是一种引用式配置改后端地址只需要改一处。extra_env是注入给工具进程的环境变量Claude Code 认ANTHROPIC_BASE_URLCodex 认OPENAI_BASE_URL这两个变量指向 openrig 的本地监听地址工具就会把请求发给 openrig 而不是直连后端。提示api_key用${VAR}引用环境变量时确保启动 openrig 的 shell 里这个变量已经 export 了否则会解析成空字符串请求到后端直接 401。3.2 Claude Code 与 Codex 的端点差异处理Claude Code 和 Codex 虽然都是 AI 编码 CLI但它们的 API 协议不一样这是 openrig 配置里最容易出错的地方。Claude Code 遵循 Anthropic 的 Messages API请求路径是/v1/messages请求体里messages数组的角色是user和assistant系统提示单独放在system字段。Codex 遵循 OpenAI 的 Responses API路径是/v1/responses请求体结构不同工具调用和流式响应的格式也有差异。openrig 在转发的时候要处理这个差异。如果后端是原生支持 Anthropic 协议的服务Claude Code 的请求可以直接透传如果后端只支持 OpenAI 协议openrig 就得做协议转换把 Messages 格式转成 Responses 格式。反过来 Codex 接 Anthropic 风格的后端也一样。这个转换逻辑是 openrig 的核心价值之一但也是最容易出 bug 的地方。实际操作中我建议先确认后端服务支持哪种协议。本地跑 LM Studio 的话它同时提供 OpenAI 兼容端点和部分 Anthropic 兼容端点但路径和字段支持程度不一样。你可以先用 curl 手动测一下curl http://127.0.0.1:1234/v1/models能列出模型说明 OpenAI 兼容端点通了。再测 Anthropic 风格curl http://127.0.0.1:1234/v1/messages \ -H Content-Type: application/json \ -d {model:qwen2.5-coder,max_tokens:100,messages:[{role:user,content:hi}]}如果这个返回正常Claude Code 接这个端点问题不大。如果报 404 或者格式错误说明后端不支持 Anthropic 协议得靠 openrig 做转换或者换一个支持的后端。Codex 那边同理先测/v1/responses端点。社区里the gpt-5.6-sol model is not supported when using codex with a...这类报错往往是模型名和后端实际提供的模型对不上或者 Codex 的配置里模型名写错了。排查的时候先确认后端/v1/models返回的列表里有没有你写的那个名字大小写、连字符都要对。3.3 环境变量注入与配置隔离openrig 启动工具进程的时候环境变量的注入顺序和覆盖规则很关键。一般来说openrig 会先继承当前 shell 的环境变量然后叠加 YAML 里extra_env定义的值最后再注入一些运行时生成的变量比如本地端点地址。这个顺序意味着extra_env里的值会覆盖 shell 里同名的变量这是符合预期的因为 YAML 配置应该优先。但这里有个坑Claude Code 和 Codex 可能读同一个环境变量名但期望不同的值。比如某些版本里两者都读OPENAI_API_KEY但一个要的是本地模型的占位 key另一个要的是远程 API 的真实 key。如果两个工具同时启用环境变量就会打架。openrig 的解法是给每个工具启动独立的子进程子进程的环境变量互相隔离不共享。你自己手动配置的时候也要注意这点别在一个 shell 里同时 export 两个工具需要的冲突变量。配置隔离还体现在配置目录上。Claude Code 默认读~/.claude/settings.json或者项目目录下的.claude文件夹Codex 读自己的配置路径。openrig 一般不改这些默认路径而是通过环境变量把端点指向本地工具的其他配置还是走自己的目录。这样你原来的 Claude Code 配置、快捷键、历史记录都不受影响只是请求走了 openrig 的转发。注意如果你之前手动改过 Claude Code 的ANTHROPIC_BASE_URL指向别的地址启用 openrig 前先把这个变量清掉或者注释掉否则 openrig 注入的值可能被旧值覆盖请求发到了错误的地方。4. 实操过程与核心环节实现4.1 从零搭建 openrig 运行环境假设你是一台干净的机器什么都没装完整流程是这样的。第一步装 Node.js去官网下载 LTS 版本Windows 下直接下.msi安装包双击macOS 用.pkg或者 HomebrewLinux 用包管理器或者 nvm。装完验证node -v npm -v两个命令都能输出版本号就说明装好了。如果node -v报 command not found检查 PATH 有没有配好Windows 下重开一个终端试试环境变量刷新需要新会话。第二步装 openrig。如果它发布在 npm 上直接全局安装npm install -g openrig如果是从源码跑先 clone 仓库再装依赖git clone openrig-repo cd openrig npm install npm run build第三步准备 YAML 配置文件。在项目目录或者用户目录下建一个openrig.yaml按上一节的结构填好你的端点和工具配置。第一次配建议只启用一个工具比如先只配 Claude Code跑通了再加 Codex减少变量。第四步启动 openrigopenrig start --config ./openrig.yaml启动后它会监听 YAML 里配的端口默认 8080。看到日志里打出listening on 127.0.0.1:8080就说明起来了。这时候另开一个终端启动 Claude Code它会读环境变量里的ANTHROPIC_BASE_URL如果 openrig 注入成功请求就会走本地转发。4.2 接入本地模型 LM Studio 的完整配置LM Studio 是本地跑模型比较省心的选择图形界面下载模型、一键启动服务。它默认监听1234端口提供 OpenAI 兼容端点。openrig 接 LM Studio 的配置重点在端点地址和模型名要对上。先在 LM Studio 里加载一个编码能力强的模型比如 Qwen2.5-Coder 或者 DeepSeek-Coder启动本地服务确认http://127.0.0.1:1234/v1/models能返回模型列表。然后在 openrig 的 YAML 里这样配endpoints: lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: lm-studio models: - qwen2.5-coder-7b-instruct tools: claude-code: enabled: true endpoint: lmstudio model: qwen2.5-coder-7b-instruct extra_env: ANTHROPIC_BASE_URL: http://127.0.0.1:8080 ANTHROPIC_API_KEY: lm-studio这里ANTHROPIC_API_KEY填lm-studio是占位LM Studio 不校验 key但 Claude Code 要求这个变量存在不填会报错。模型名必须和 LM Studio 里加载的模型标识完全一致去/v1/models的返回里复制别手打。启动 openrig 后再启动 Claude Code发一条测试消息看 openrig 的日志里有没有转发记录。如果日志显示请求进来了但转发失败多半是模型名不对或者 LM Studio 那边模型没加载好。如果 Claude Code 直接报连接错误检查ANTHROPIC_BASE_URL是不是真的指向了 openrig 的端口。4.3 Codex 接入第三方 API 的配置要点Codex 接第三方 API 的配置和 Claude Code 类似但端点路径要注意。Codex 走/v1/responses如果你的第三方 API 只提供/v1/chat/completions就需要 openrig 做路径重写。YAML 里可以配一个路径映射endpoints: thirdparty: base_url: https://api.example.com/v1 api_key: ${THIRD_PARTY_KEY} path_rewrite: /v1/responses: /v1/chat/completions models: - gpt-5.6-sol tools: codex: enabled: true endpoint: thirdparty model: gpt-5.6-sol extra_env: OPENAI_BASE_URL: http://127.0.0.1:8080/v1 OPENAI_API_KEY: ${THIRD_PARTY_KEY}path_rewrite把 Codex 发的/v1/responses重写成后端支持的/v1/chat/completions。但要注意路径重写只是改了 URL请求体格式如果不一样还是会有问题。Responses API 和 Chat Completions API 的请求体结构有差异openrig 如果支持请求体转换会在转发时做映射如果不支持你可能得换一个原生支持 Responses API 的后端。第三方 API 的 key 用环境变量引用启动 openrig 前先 exportexport THIRD_PARTY_KEYyour-key-here openrig start --config ./openrig.yamlWindows 下用set THIRD_PARTY_KEYyour-key-here或者 PowerShell 的$env:THIRD_PARTY_KEYyour-key-here。key 别写进 YAML 提交到仓库这是基本的安全习惯。4.4 多工具切换与配置热更新openrig 的一个实用功能是配置热更新改完 YAML 不用重启整个服务它重新加载配置就行。这对多工具切换场景很有用你上午用 Claude Code 接本地模型写代码下午想换成 Codex 接远程 API改几行 YAML 触发重载两个工具的环境变量就切换了。热更新的触发方式一般有两种一种是发信号比如kill -HUP pid另一种是 openrig 监听配置文件变化自动重载。具体支持哪种看你的版本。手动重载的话openrig reload或者找到 openrig 的进程 ID 发信号。重载后确认日志里打出config reloaded之类的提示再验证工具是否连到了新端点。多工具同时启用的时候注意端口别冲突。openrig 自己占一个端口Claude Code 和 Codex 各自可能也有本地端口需求YAML 里配的监听端口要错开。另外两个工具同时跑会争抢本地模型的推理资源本地模型一般并发能力有限建议一次只开一个工具或者给本地模型服务配好并发队列。提示热更新虽然方便但涉及端点地址变更的时候已经建立的连接不会自动断开重连。改完配置后最好把工具进程也重启一下确保新配置完全生效。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解决安装阶段最常见的就是 Node.js 版本问题。error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个报错通常是你用的某个工具或者 npm 包指定了 Node.js 版本但那个版本还没正式发布或者你的镜像源里没有。解决办法是降到 LTS 版本去 Node.js 官网下载页选 LTS别用 Current。如果你用 nvm 管理版本nvm install --lts nvm use --lts另一个常见问题是 npm 全局安装权限不足Linux 和 macOS 下不加 sudo 会报EACCES。但我不建议直接sudo npm install -g那样装出来的包权限是 root后面更新和卸载都麻烦。正确做法是配置 npm 的全局目录到用户目录npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH然后重新npm install -g openrig不用 sudo 也能装。Windows 下如果遇到codex安装 windows桌面版相关的报错检查是不是装了多个 Node.js 版本导致 PATH 混乱。用where node看看有几个路径清理掉多余的只留一个 LTS 版本。5.2 端点转发失败的排查思路cc switch local proxy failed while handling codex endpoint /responses这类报错排查要按链路一步步来。先确认 openrig 服务本身活着curl http://127.0.0.1:8080/health或者看日志有没有监听成功。然后确认后端服务活着直接 curl 后端端点看能不能通。两头都通但转发失败问题就在 openrig 的配置上。检查 YAML 里 Codex 的端点路径配置。Codex 发的是/v1/responsesopenrig 转发的时候有没有正确匹配到这个路径。如果 YAML 里配的base_url是http://127.0.0.1:1234/v1openrig 拼接后的完整路径应该是http://127.0.0.1:1234/v1/responses确认后端真的在这个路径上提供服务。有些后端只提供/v1/chat/completions那就得配path_rewrite。再看请求头。Codex 发的请求带Authorization: Bearer keyopenrig 转发的时候有没有把这个头带上或者有没有用 YAML 里配的 key 覆盖。如果后端要求特定的头比如anthropic-versionopenrig 得注入。这些细节在 YAML 里一般有对应的配置项翻一下文档。5.3 模型不支持的报错处理the gpt-5.6-sol model is not supported when using codex with a...这个报错很直白就是模型名对不上。先去后端/v1/models拿准确列表把模型名复制过来。注意有些后端返回的模型名带版本后缀或者组织前缀比如openai/gpt-5.6-sol或者gpt-5.6-sol-20250101你 YAML 里写的必须和返回的完全一致。还有一种情况是后端支持这个模型但 Codex 的配置里模型名被别的地方覆盖了。检查环境变量里有没有OPENAI_MODEL或者类似的变量它的优先级可能高于 YAML 配置。清掉这些变量再试。如果模型名确认没错还是报不支持可能是协议不匹配。Codex 用 Responses API 发请求后端只支持 Chat Completions模型虽然存在但接口不认。这时候要么换支持 Responses API 的后端要么靠 openrig 做协议转换要么把 Codex 的端点指向一个兼容层。5.4 常见问题速查表报错关键词可能原因排查动作node.js vXX not yet releasedNode.js 版本过新或镜像源缺失降到 LTS 版本换官方源EACCES permission deniednpm 全局目录权限不足配置 npm prefix 到用户目录proxy failed handling endpoint端点路径不匹配或后端未启动分别 curl 前后端检查 path_rewritemodel is not supported模型名错误或协议不匹配核对 /v1/models 列表检查协议401 UnauthorizedAPI Key 未注入或为空检查环境变量是否 exportYAML 引用是否正确connection refusedopenrig 或后端未监听确认端口检查防火墙config parse errorYAML 缩进或语法错误用 YAML 校验工具检查统一用空格5.5 我踩过的几个坑第一个坑是 YAML 里的布尔值。YAML 会把yes、no、on、off解析成布尔值如果你某个字段想写字符串on不加引号就变成true了。openrig 配置里enabled字段是布尔值没问题但如果有别的字段期望字符串记得加引号。第二个坑是环境变量里的路径。Windows 下路径带反斜杠YAML 里写的时候要么用正斜杠要么用双引号包起来否则反斜杠会被当转义符。比如C:\Users\name在 YAML 里可能被解析成奇怪的东西写成C:/Users/name或者C:\\Users\\name更稳。第三个坑是端口占用。openrig 默认 8080但 8080 经常被别的开发服务占了。启动前用netstat -ano | findstr 8080Windows或者lsof -i :8080macOS/Linux查一下占了就换端口YAML 里改global.port就行。第四个坑是本地模型的上下文长度。本地跑的模型上下文窗口往往比云端小Claude Code 或者 Codex 发过去的请求可能超出窗口后端直接报错。这种情况要么换上下文更大的模型要么在 openrig 里配请求截断要么在工具侧限制发送的上下文量。6. 配置扩展与工作流集成6.1 把 openrig 配置纳入版本管理openrig 的 YAML 配置适合纳入 Git 管理但密钥不能提交。做法是把配置拆成两部分openrig.yaml放结构化的非敏感配置openrig.local.yaml放密钥和本地路径后者加到.gitignore里。openrig 启动时支持配置合并先读主配置再读本地覆盖openrig start --config ./openrig.yaml --override ./openrig.local.yaml这样团队协作的时候主配置可以共享每个人根据自己的环境写本地覆盖文件。密钥用环境变量引用本地文件里只写变量名不写值值放在 shell 的 profile 里或者用密钥管理工具注入。6.2 与 VS Code 的配合使用很多人用 Claude Code 或 Codex 是在 VS Code 的集成终端里openrig 的配置对这种方式同样有效。VS Code 的终端继承系统的环境变量只要 openrig 注入的环境变量在终端里可见Claude Code 的 VS Code 扩展或者终端里的 CLI 都能走 openrig 转发。如果你用claude code for vs code这个扩展注意扩展可能有自己的配置入口检查扩展设置里有没有覆盖ANTHROPIC_BASE_URL。有的话改成 openrig 的地址或者清空让它读环境变量。VS Code 的settings.json里也可以配终端的环境变量{ terminal.integrated.env.linux: { ANTHROPIC_BASE_URL: http://127.0.0.1:8080 } }Windows 下把linux换成windowsmacOS 换成osx。这样每次开终端自动带上变量不用手动 export。6.3 后续可以扩展的方向openrig 这套 YAML 驱动的思路可以往外延伸不少。比如加一个配置模板功能预置几套常用组合——本地模型开发模式、远程 API 生产模式、混合模式切换的时候直接选模板不用手改 YAML。再比如加健康检查openrig 定期探测后端端点挂了自动切换到备用端点提高可用性。还可以做配置校验启动前用 JSON Schema 校验 YAML 的结构和字段类型把拼写错误、类型错误提前拦下来而不是等到运行时才报错。这个对新手特别友好能省掉大量排查时间。如果你想把 openrig 集成到 CI 或者自动化脚本里它的 CLI 接口可以进一步封装比如提供openrig test命令自动跑一遍端点连通性测试输出每个工具每个端点的状态报告。这样部署前跑一下心里有底。我个人在实际操作中的体会是openrig 这类工具的价值不在于它做了多复杂的事而在于它把原本散落各处的配置收敛到了一处用声明式的方式管理。你花半小时把 YAML 配好后面切换工具、换模型、加新端点都是改几行配置的事不用再翻每个工具的文档重新折腾。这个投入产出比在长期使用中会越来越明显。最后再分享一个小技巧把常用的 curl 测试命令写成 shell 脚本每次改完配置跑一遍比在工具里试错快得多也更容易定位问题出在哪一层。