1. openrig 到底是个什么东西第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者机械臂项目毕竟 rig 这个词在工程领域通常指“装配、支架、测试台”。但结合它周围高频出现的 claude code、codex、yaml、node.js 这些词基本可以判断openrig 是一套围绕 AI 编程助手尤其是命令行形态的 agent 工具搭建的本地配置与运行框架。它的核心价值在于把 claude code、codex 这类工具的安装、模型接入、代理转发、配置管理统一到一套可复用的结构里让你不用每次换工具就重新折腾一遍环境。我最初接触这类需求是因为团队里同时有人在用 claude code有人在用 codex还有人想接本地模型跑。每个人的配置文件散落在不同目录yaml 格式不统一node.js 版本也各不相同结果就是“你那边能跑我这边报错”。openrig 想解决的正是这个痛点用一套约定好的目录结构和 yaml 配置把工具链、模型端点、代理规则全部收拢做到换机器、换工具、换模型时只改配置不改流程。它适合谁如果你只是偶尔用一下网页版 AI 对话那暂时用不上。但如果你已经在终端里跑 claude code 或 codex或者准备把 AI 编程助手接入自己的本地模型、第三方 API那 openrig 这类框架能帮你省掉大量重复劳动。尤其是那些遇到 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错就头大的人理解 openrig 的组织方式之后排查问题的思路会清晰很多。需要先说明一点openrig 目前并不是一个官方统一发布的标准产品更像是一类项目组织方式的统称。不同人手里的 openrig 目录可能长得不一样但核心逻辑相通——用 yaml 描述配置用 node.js 做运行时用代理层做协议转换最终让 claude code 和 codex 都能稳定工作。下面我按自己实际搭建和踩坑的经验把这套东西拆开讲。2. 整体设计与思路拆解2.1 为什么要把 claude code 和 codex 放在一起管单独装 claude code 或者单独装 codex其实都不算太复杂。官方文档给几条命令node.js 装好npm 全局安装登录账号就能跑。但问题出在“同时用”和“换着用”的时候。claude code 有自己的配置目录和认证方式codex 也有自己的配置文件和环境变量两者的模型端点、请求格式、代理需求都不一样。你今天想用 claude code 调本地模型明天想用 codex 接第三方 API如果每次都手动改环境变量、改配置文件很快就会乱。openrig 的思路是抽象出一层“运行时配置”。它不直接替代 claude code 或 codex而是在它们之上做编排。具体来说它用 yaml 文件描述三件事第一当前要用哪个工具claude code 还是 codex第二这个工具要连哪个模型端点官方、第三方还是本地第三请求经过哪些代理或转换层。这样一来切换工具或模型只需要改 yaml不用动工具本身的安装。这个设计的好处很明显。首先是可复现你把 openrig 目录复制到另一台机器装好 node.js改一下本机路径基本就能跑起来。其次是可排查出问题的时候先看 yaml 配置再看代理日志最后才怀疑工具本身排查路径短。最后是可扩展以后想加新的 AI 编程工具只要在 yaml 里加一段配置不用重新设计整个流程。2.2 yaml 作为配置核心的取舍为什么选 yaml 而不是 json 或 toml这里有几个实际考虑。json 虽然通用但不支持注释配置多了之后很难标注哪一行是干什么的。toml 表达力不错但在 node.js 生态里yaml 的解析库更成熟和很多工具的配置文件格式也一致。更重要的是claude code 和 codex 本身的一些配置就涉及 yaml 或类似结构用 yaml 做统一层减少格式转换的心智负担。不过 yaml 也有坑。缩进必须用空格不能用 tab冒号后面要加空格字符串里有特殊字符要引号。我见过不少人因为 yaml 缩进错了一位导致整个配置解析失败然后花半小时找问题。所以 openrig 的 yaml 文件建议用支持 yaml 语法高亮的编辑器打开比如 vscode 装 yaml 插件能提前发现大部分格式错误。另一个取舍是配置粒度。太粗了不够灵活太细了维护成本高。我的经验是分三层全局层放 node.js 路径、日志级别、代理端口工具层放 claude code 和 codex 各自的启动参数和模型端点模型层放具体模型的 API 地址、密钥环境变量名、请求超时。这样改模型不用动工具配置改工具不用动全局设置。2.3 node.js 在其中的角色与版本选择openrig 依赖 node.js主要是因为 claude code 和 codex 的 cli 工具大多通过 npm 分发代理层也常用 node.js 写。node.js 在这里既是运行时也是包管理器。你不需要成为 node.js 专家但必须理解版本管理的基本逻辑。node.js 的版本分 LTS 和 Current。LTS 是长期支持版稳定适合生产环境Current 是新特性版更新快但可能有不兼容。openrig 这类工具链建议用 LTS比如 node.js 20 或 22 的 LTS 版本。我试过用 Current 版本跑某些代理库遇到原生模块编译失败换回 LTS 就好了。另外如果你机器上已经有其他项目依赖不同 node.js 版本建议用 nvm 或 fnm 做版本切换不要直接覆盖系统 node.js。还有一个常见报错“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”。这通常是因为 package.json 或某个依赖指定了一个不存在的 node.js 版本或者镜像源里还没有这个版本。解决办法是检查 engines 字段改成实际存在的 LTS 版本或者用 nvm 安装一个可用版本再重试。3. 核心细节解析与实操要点3.1 目录结构怎么摆才不乱openrig 的目录结构没有强制标准但根据我多次搭建的经验下面这套布局最顺手openrig/ ├── config/ │ ├── global.yaml │ ├── claude-code.yaml │ ├── codex.yaml │ └── models.yaml ├── scripts/ │ ├── start-claude.sh │ ├── start-codex.sh │ └── switch-model.sh ├── logs/ │ ├── claude-code.log │ └── codex.log ├── proxy/ │ └── local-proxy.js └── package.jsonconfig 目录放所有 yaml 配置按全局、工具、模型分开。scripts 目录放启动脚本每个工具一个方便单独调试。logs 目录集中放日志出问题先看这里。proxy 目录放本地代理脚本如果不需要代理可以留空。package.json 用来声明 node.js 依赖和脚本命令。这个结构的好处是职责清晰。你想改模型端点只动 models.yaml想改 claude code 启动参数只动 claude-code.yaml想看运行日志直接进 logs。不会出现“改了一个地方另一个工具挂了”的情况。3.2 yaml 配置文件的关键字段与写法先看 global.yaml它放全局设置node: path: /usr/local/bin/node version: 20.11.0 proxy: enabled: true port: 8787 logLevel: info logging: level: debug dir: ./logsnode.path 指定 node.js 可执行文件路径多版本环境下这个很重要。proxy.port 是本地代理监听端口后面 claude code 和 codex 都指向这个端口。logging.level 控制日志详细程度排查问题时调成 debug平时用 info。再看 models.yaml它描述模型端点models: local-qwen: type: openai-compatible baseUrl: http://127.0.0.1:1234/v1 apiKeyEnv: LOCAL_API_KEY timeout: 120000 deepseek-v4: type: openai-compatible baseUrl: https://api.deepseek.com/v1 apiKeyEnv: DEEPSEEK_API_KEY timeout: 60000这里 type 字段很关键。openai-compatible 表示这个端点兼容 OpenAI 的请求格式大多数第三方 API 和本地模型服务都支持。baseUrl 是端点地址注意本地模型通常用 127.0.0.1 而不是 localhost避免某些环境下的解析问题。apiKeyEnv 指定从哪个环境变量读密钥不要把密钥直接写在 yaml 里。timeout 是请求超时本地模型推理慢的话要调大。claude-code.yaml 和 codex.yaml 分别描述两个工具的配置# claude-code.yaml tool: claude-code model: local-qwen proxy: true args: - --dangerously-skip-permissions env: ANTHROPIC_BASE_URL: http://127.0.0.1:8787# codex.yaml tool: codex model: deepseek-v4 proxy: true args: - --model - gpt-5.6-sol env: OPENAI_BASE_URL: http://127.0.0.1:8787/v1注意 codex 的 baseUrl 后面要加 /v1而 claude code 的 ANTHROPIC_BASE_URL 通常不加。这是因为两个工具对端点路径的处理方式不同。如果你遇到 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错先检查这个路径拼接对不对。3.3 本地代理层的作用与实现要点代理层是 openrig 里最容易出问题也最值得花时间理解的部分。它的核心作用有三个第一统一请求入口让 claude code 和 codex 都指向同一个本地端口第二做协议转换比如把 Anthropic 格式的请求转成 OpenAI 格式第三记录日志方便排查。一个最简代理可以用 node.js 的 http 模块写const http require(http); const { createProxyMiddleware } require(http-proxy-middleware); const target process.env.TARGET_BASE_URL || http://127.0.0.1:1234; const server http.createServer((req, res) { console.log([proxy] ${req.method} ${req.url}); // 这里做路径重写和头部处理 // ... }); server.listen(8787, 127.0.0.1, () { console.log(proxy listening on 8787); });实际项目中你可能需要根据请求路径判断转发到哪个模型端点还要处理流式响应。流式响应是 AI 编程工具的核心需求如果代理层不支持 stream工具会一直卡住或者报错。我建议用成熟的代理库比如 http-proxy-middleware它已经处理了大部分边界情况。代理层的日志一定要开。我排查 “codex 无法加载组织设置” 这类问题时就是靠代理日志发现请求头里少了某个字段。日志里至少记录请求方法、请求路径、目标地址、响应状态码、耗时。不要记录完整的请求体和响应体里面有代码和密钥不安全。3.4 环境变量与密钥管理openrig 涉及多个工具和模型密钥管理不能马虎。基本原则是密钥只放环境变量不放 yaml不放代码不进 git。你可以用一个 .env 文件在本地加载但 .env 要加到 .gitignore 里。常见的环境变量命名变量名用途示例值ANTHROPIC_API_KEYclaude code 官方密钥sk-ant-xxxOPENAI_API_KEYcodex 或 OpenAI 兼容端点密钥sk-xxxDEEPSEEK_API_KEYDeepSeek 端点密钥sk-xxxLOCAL_API_KEY本地模型密钥通常随便填localTARGET_BASE_URL代理转发目标http://127.0.0.1:1234启动脚本里用 source .env 或者 dotenv 库加载。注意不要把 .env 提交到仓库也不要在日志里打印密钥。我见过有人把密钥写在 yaml 里然后不小心推到公开仓库结果密钥被滥用。这种坑一次就够。4. 实操过程与核心环节实现4.1 从零搭建 openrig 的完整步骤假设你在一台 Ubuntu 机器上从零开始搭建。第一步安装 node.js。推荐用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v如果你在 Windows 上可以用 nvm-windows 或者直接下载 node.js LTS 安装包。安装完成后node -v 和 npm -v 都能正常输出版本号。第二步创建 openrig 目录和基础文件mkdir -p openrig/{config,scripts,logs,proxy} cd openrig npm init -y npm install http-proxy-middleware dotenv js-yaml第三步写配置文件。按前面说的 global.yaml、models.yaml、claude-code.yaml、codex.yaml 分别创建。注意 yaml 缩进用两个空格不要用 tab。第四步写启动脚本。以 claude code 为例#!/bin/bash source .env export ANTHROPIC_BASE_URLhttp://127.0.0.1:8787 npx anthropic-ai/claude-codecodex 的启动脚本类似只是环境变量和命令不同。给脚本加执行权限chmod x scripts/*.sh。第五步启动代理。可以单独开一个终端跑 node proxy/local-proxy.js也可以写进启动脚本里后台运行。我习惯单独开终端方便看日志。第六步测试。先跑 claude code看能不能正常对话。再跑 codex看能不能正常对话。如果某个工具报错先看代理日志再看工具自己的日志。4.2 接入本地模型的参数计算与调试接入本地模型时有几个参数需要根据机器性能调整。第一个是 timeout。本地模型推理速度取决于显卡和模型大小。7B 模型在消费级显卡上生成 1000 token 可能需要 30 秒到 1 分钟。所以 timeout 至少设 120000 毫秒也就是 2 分钟。如果模型更大还要往上加。第二个是并发数。本地模型服务通常不支持高并发如果你同时开 claude code 和 codex两个请求一起打到本地模型可能会排队甚至超时。解决办法是在代理层做请求队列或者错开使用时间。我试过同时跑两个工具结果两个都卡住后来改成一次只跑一个就稳定了。第三个是上下文长度。本地模型的上下文窗口通常比云端模型小比如 8K 或 32K。如果你让 claude code 读一个大项目上下文很容易超。这时候要么换更大上下文的模型要么在工具里限制读取范围。claude code 有参数可以控制读取的文件数量具体看官方文档。调试本地模型接入时先用 curl 直接测端点curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:local-qwen,messages:[{role:user,content:hello}]}如果 curl 能通说明模型服务正常问题在代理或工具配置。如果 curl 不通先解决模型服务本身的问题。4.3 claude code 与 codex 的差异化配置claude code 和 codex 虽然都是 AI 编程助手但配置上有几个关键差异。第一环境变量名不同。claude code 用 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEYcodex 用 OPENAI_BASE_URL 和 OPENAI_API_KEY。第二端点路径不同。claude code 的 baseUrl 通常不带 /v1codex 的 baseUrl 通常带 /v1。第三认证方式可能不同。claude code 支持订阅登录codex 可能用 API key 或组织认证。如果你遇到 “your organization has disabled claude subscription access for claude code” 这类提示说明你的账号订阅权限被组织限制了。这时候要么换账号要么改用 API key 认证。API key 认证需要在环境变量里设置 ANTHROPIC_API_KEY而不是依赖订阅登录。codex 的 “无法加载组织设置” 通常是网络问题或认证问题。先检查 OPENAI_API_KEY 是否设置正确再检查代理是否正常转发。如果代理日志里看到 401 或 403说明认证失败如果看到超时说明网络不通。4.4 用 cc switch 切换模型时的注意事项cc switch 这类工具的作用是在不同模型配置之间快速切换。用的时候要注意几点。第一切换后要重启 claude code 或 codex因为环境变量在进程启动时读取运行中改配置不生效。第二切换模型后先跑一个简单测试确认新模型能正常响应再开始正式工作。第三不同模型的请求格式可能有细微差异比如某些模型不支持 system role或者对 temperature 范围要求不同。如果切换后报格式错误先看模型文档。我自己的做法是给每个常用模型写一个启动脚本比如 start-claude-local.sh、start-claude-deepseek.sh切换时直接跑对应脚本比用 cc switch 更直观。脚本里把环境变量和参数都写死减少运行时变量。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解决安装阶段最常见的问题是 node.js 版本不对。报错 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available” 说明你或某个依赖指定了一个不存在的版本。解决办法是检查 package.json 的 engines 字段改成实际存在的 LTS 版本比如 “20.0.0”。然后用 nvm 安装对应版本。第二个常见问题是 npm 全局安装权限不足。在 Linux 或 macOS 上直接 npm install -g 可能报 EACCES 错误。解决办法是用 nvm 管理 node.js这样全局包安装在用户目录下不需要 sudo。如果你已经用了系统 node.js可以配置 npm 的 prefix 到用户目录。第三个问题是网络超时。npm 默认从官方源下载国内可能很慢。可以换镜像源但注意不要用来源不明的镜像。换源命令是 npm config set registry具体地址自己查官方文档。5.2 运行阶段的代理报错排查“cc switch local proxy failed while handling codex endpoint /responses” 这个报错核心是代理在处理 codex 的 /responses 端点时失败了。排查步骤第一看代理日志确认请求有没有到达代理第二看目标地址确认代理转发到了正确的模型端点第三看响应状态码如果是 404说明路径拼接错了如果是 500说明目标服务内部错误如果是超时说明网络或模型推理太慢。路径拼接错误很常见。codex 请求的路径可能是 /v1/responses而你的代理转发到了 /responses少了 /v1。解决办法是在代理层做路径重写或者把 baseUrl 配成带 /v1 的完整地址。我建议在代理日志里打印原始路径和目标路径一眼就能看出问题。另一个常见问题是流式响应中断。AI 编程工具通常用 SSE 流式接收响应如果代理层没有正确处理 chunked 传输响应会断断续续或者直接卡住。解决办法是用支持流式的代理库或者在代理层手动处理 data 事件确保每个 chunk 都转发出去。5.3 模型接入的兼容性问题不同模型对 OpenAI 兼容 API 的支持程度不一样。有些模型不支持 function calling而 claude code 和 codex 可能依赖这个功能。如果工具报 “model does not support tools” 之类的错误说明当前模型不支持工具调用。解决办法是换一个支持 function calling 的模型或者在工具配置里关闭工具调用功能。还有些模型对请求体里的字段很敏感。比如某些模型不接受 stream_options 字段或者对 max_tokens 有上限要求。如果报 400 错误先看响应体里的错误信息通常会指出哪个字段有问题。然后对照模型文档调整。本地模型还有一个常见问题是 tokenizer 不一致。云端模型的 token 计数和本地模型可能不同导致同样的文本在本地模型里超上下文。解决办法是留足余量比如模型标称 32K 上下文实际只用 24K。5.4 常见问题速查表报错或现象可能原因排查方向解决办法node.js 版本不存在engines 字段指定了未发布版本检查 package.json改成 LTS 版本npm 安装权限不足系统 node.js 全局目录无写权限检查 npm prefix用 nvm 管理 node.js代理 404路径拼接错误看代理日志的原始路径和目标路径修正 baseUrl 或路径重写代理超时模型推理慢或网络不通看代理日志耗时调大 timeout检查网络流式响应中断代理不支持 chunked 传输看代理是否逐块转发换支持流式的代理库模型不支持工具调用模型能力限制看工具报错信息换模型或关闭工具调用认证失败 401密钥错误或未设置检查环境变量重新设置 API key组织设置无法加载网络或认证问题看代理日志状态码检查密钥和网络yaml 解析失败缩进或格式错误用 yaml 插件检查修正缩进和冒号空格上下文超限模型窗口小或读取文件太多看模型文档和工具配置换大窗口模型或限制读取5.5 我踩过的几个坑和独家建议第一个坑是 yaml 里的布尔值。yaml 会把 yes、no、on、off 解析成布尔值而不是字符串。如果你某个配置项需要字符串 “on”必须加引号写成 “on”。我因为这个坑排查了半小时最后发现是 yaml 自动转换了类型。第二个坑是环境变量加载顺序。启动脚本里如果先启动工具再 source .env环境变量不会生效。正确顺序是先 source .env再启动工具。另外如果你在 .env 里定义了同名变量它会覆盖系统环境变量注意不要冲突。第三个坑是代理端口被占用。8787 这个端口很多工具默认用如果被占用代理启动会失败。解决办法是换一个不常用的端口比如 18787或者先查端口占用lsof -i :8787。第四个坑是日志文件太大。debug 级别日志在长时间运行后会占满磁盘。建议用 logrotate 或者定期清理或者把日志级别调成 info只在排查时开 debug。第五个坑是直接复制别人的配置。不同机器路径不同node.js 路径、模型端点地址、密钥环境变量名都可能不一样。复制配置后一定要逐项检查不要直接跑。6. 后续扩展与个人体会openrig 这套结构搭好之后扩展起来很灵活。比如你想加一个新的 AI 编程工具只需要在 config 目录加一个 yaml在 scripts 目录加一个启动脚本代理层如果兼容就不用改。你想加一个新的模型端点只需要在 models.yaml 里加一段然后在工具配置里引用。这种模块化设计让整个工具链的维护成本低很多。我个人的体会是这类工具链的稳定性不取决于单个工具多强大而取决于配置管理和问题排查是否顺畅。openrig 的价值就在于把配置集中、日志集中、切换流程标准化。你不需要记住每个工具的环境变量名只需要看 yaml你不需要在每个工具目录里翻日志只需要看 logs。这种一致性在长期使用中会省下大量时间。最后分享一个小技巧给 openrig 目录做一个 git 仓库但把 .env、logs、node_modules 加到 .gitignore。这样你可以追踪配置变更出问题时回滚到上一个可用版本。配置变更也写 commit message比如 “switch codex to deepseek-v4”以后回头看很清楚。这个习惯我坚持了半年至少帮我省了三次重装环境的时间。