1. 从 openrig 说起一个被低估的本地 AI 编码环境编排工具第一次看到openrig这个名字我下意识把它和“开源钻机”联系到了一起毕竟 rig 在工程领域就是钻井平台、测试台架的意思。但真正把它跑起来、翻完它的配置目录之后我才意识到这个名字起得相当贴切——它本质上就是给本地 AI 编码助手搭的一套“钻井平台”把 Claude Code、Codex 这类命令行智能体和本地模型、第三方 API、YAML 配置、Node.js 运行时这些东西全部固定在一个可复现的支架上。如果你最近在折腾 Claude Code 或者 Codex 的本地部署大概率踩过这些坑cc switch local proxy failed while handling codex endpoint /responses这种代理转发报错、your organization has disabled claude subscription access for claude code这种权限拦截、error installing 24.21.0: node.js v24.21.0 is not yet released这种版本对不上的问题。这些错误的共同点是——它们都不是模型本身的问题而是环境编排的问题。openrig 想解决的恰恰就是这一层。我写这篇东西的目的很直接把 openrig 这套思路拆开讲清楚它为什么要把 YAML、Node.js、Claude Code、Codex 这几样东西绑在一起每一层该怎么配配的时候哪些参数是坑以及当代理转发失败、模型不被支持、组织策略拦截时应该从哪里下手排查。适合已经装过 Claude Code 或 Codex、但被环境问题卡住的开发者也适合想给团队搭一套统一本地编码环境的人。全文基于我自己的实操记录和常见实践补充不保证覆盖所有发行版但核心逻辑是通的。2. openrig 的整体设计思路为什么是 YAML Node.js 多智能体2.1 把“环境”当成代码来管而不是当成一次性命令大部分人装 Claude Code 或 Codex 的方式是这样的打开终端npm install -g一把梭然后claude或codex直接跑。第一次能跑通换台机器、换个 Node 版本、换个模型供应商立刻崩。这就是典型的“环境没有版本化”。openrig 的核心设计哲学是把整个 AI 编码环境描述成一份声明式的配置。你告诉它“我要 Node.js 20、要 Claude Code、要 Codex、Codex 走哪个 endpoint、用哪个模型”它负责把运行时、CLI 工具、代理转发、模型映射全部对齐。这跟 Docker Compose 管容器、Terraform 管云资源的思路是一模一样的——环境即代码。为什么非得用 YAML因为 YAML 在“人类可读”和“机器可解析”之间取得了最好的平衡。JSON 写注释费劲TOML 嵌套深了难看YAML 既能写多行字符串比如系统提示词又能表达层级比如不同智能体走不同 provider还能被 Node.js 生态里的js-yaml、yaml包直接解析。你在热搜里看到的yaml安装、yaml文件、yolov10 yaml文件怎么创建其实都指向同一个需求用一份结构化文件描述复杂配置。openrig 把这份能力用在了 AI 编码环境上。2.2 为什么运行时锁定 Node.js 20而不是随便一个 LTSClaude Code 和 Codex 的 CLI 都是 Node.js 写的这一点从它们的安装方式就能看出来。但版本选择上有讲究。热搜里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava就是典型的版本踩坑——你照着某个教程敲了一个不存在的版本号npm 直接拒绝。openrig 的实践里Node.js 20 LTS 是甜点版本。原因有三第一Claude Code 和 Codex 的依赖树里有一批包对 Node 18 已经不再保证兼容Node 18 在 2025 年已经进入维护末期第二Node 22 虽然更新但部分原生模块比如某些终端渲染库在 22 上的预编译产物还不全容易触发 node-gyp 编译第三Node 20 的--experimental-vm-modules和 fetch API 已经足够稳定代理转发脚本用起来不会出幺蛾子。所以 openrig 的 YAML 里通常会显式声明node: 20 22这样的约束而不是笼统写个latest。这个约束会在环境初始化时被校验版本不对直接报错退出避免你跑到一半才发现 CLI 起不来。2.3 多智能体共存Claude Code 和 Codex 不是二选一很多人以为 Claude Code 和 Codex 是竞品装一个就行。实际用下来它们的能力边界不一样。Claude Code 在长上下文理解、多文件重构、终端命令编排上更顺手Codex 在某些代码补全、特定语言模式、以及接入第三方模型比如codex接入deepseek时更灵活。openrig 的设计是让两者共存通过 YAML 里的 profile 切换而不是让你反复卸载重装。这就引出了 openrig 最关键的一层代理转发与模型映射。当 Codex 要调用一个非默认模型时它需要一个兼容 OpenAI 接口的 endpoint。热搜里的cc switch local proxy failed while handling codex endpoint /responses说的就是这个环节——本地代理在处理 Codex 的/responses请求时挂了。openrig 把这一层单独抽出来配置就是为了让代理失败时能快速定位而不是埋在 CLI 的黑盒里。3. 核心配置细节YAML 文件到底该写什么3.1 一份可复现的 openrig 配置骨架下面这份 YAML 是我在实际项目里用的骨架去掉了敏感信息保留了结构。你可以直接抄然后按需改。version: 1 runtime: node: 20 22 packageManager: npm agents: claude: enabled: true command: claude env: ANTHROPIC_BASE_URL: http://127.0.0.1:8787 ANTHROPIC_API_KEY: ${CLAUDE_KEY} profiles: default: model: claude-sonnet local: model: lmstudio-local baseUrl: http://127.0.0.1:1234/v1 codex: enabled: true command: codex env: OPENAI_BASE_URL: http://127.0.0.1:8787/v1 OPENAI_API_KEY: ${CODEX_KEY} profiles: default: model: gpt-5.6-sol deepseek: model: deepseek-chat baseUrl: https://api.deepseek.com/v1 proxy: enabled: true listen: 127.0.0.1:8787 routes: - match: /v1/responses target: codex - match: /v1/messages target: claude timeoutMs: 120000 retry: attempts: 3 backoffMs: 500这份配置里有几个点值得单独说。runtime.node的约束前面解释过了。agents下面每个智能体都有env和profilesenv决定它启动时读哪些环境变量profiles决定它调用哪个模型、走哪个 baseUrl。proxy段是 openrig 的枢纽它监听本地 8787 端口按路径把请求分发给不同的智能体后端。注意${CLAUDE_KEY}这种写法是环境变量插值不要把真实密钥写进 YAML 文件。openrig 在加载时会从进程环境里读取这样配置文件可以进版本库密钥留在本地。3.2 代理路由的匹配逻辑与常见失败点cc switch local proxy failed while handling codex endpoint /responses这个报错十有八九出在routes的匹配上。Codex 在调用模型时请求路径是/v1/responses注意是 responses 不是 chat/completions而 Claude Code 走的是/v1/messages。如果你的代理只配了/v1/chat/completions这一条路由Codex 的请求就会落空代理返回 404 或者直接抛异常。openrig 的匹配规则是前缀匹配 最长优先。也就是说/v1/responses和/v1/responses/stream都会命中同一条路由但如果有更长的匹配项会优先用更长的。这个设计是为了兼容流式和非流式两种请求。实操中我建议把routes写全至少覆盖/v1/responses、/v1/messages、/v1/chat/completions三条哪怕某条暂时用不上留着也不会出错。另一个高频失败点是timeoutMs。Codex 在处理大文件重构时单次请求可能跑好几分钟。默认超时如果只有 30 秒代理会在模型还没返回时就断开CLI 那边看到的就是“代理处理失败”。我一般把timeoutMs设到 120000两分钟起步复杂项目设到 300000。retry段也别省网络抖动时自动重试能省掉很多手动重跑的麻烦。3.3 模型映射gpt-5.6-sol不被支持时怎么办热搜里那条{detail:the gpt-5.6-sol model is not supported when using codex with a是个典型问题。Codex 的默认配置里可能写了一个特定模型名但你接的第三方 endpoint 根本不认识这个名字。openrig 的做法是在profiles里做模型别名映射CLI 层面看到的模型名和实际发给后端的模型名可以不一样。具体来说你可以在代理层加一个modelMapproxy: modelMap: gpt-5.6-sol: deepseek-chat claude-sonnet: qwen-max这样 Codex 以为自己调用的是gpt-5.6-sol代理转发时把它替换成后端真正支持的deepseek-chat。这个技巧在codex接入deepseek、claude code 调用lmstudio的本地模型这类场景里特别有用——CLI 的模型名是写死的但后端千变万化中间加一层映射就解耦了。提示模型映射要放在代理层做不要试图去改 CLI 的源码或配置文件。CLI 升级后你的改动会被覆盖代理层则是稳定的。4. 实操过程从零把 openrig 跑起来4.1 Node.js 20 的安装与版本校验第一步永远是运行时。Ubuntu 上装 Node.js 20我不推荐用系统自带的 apt 源版本太旧。用 NodeSource 的源或者 nvm 都行。nvm 的好处是可以在多个版本间切换适合同时维护多个项目的场景。# 用 nvm 安装 Node 20 LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v # 应该输出 v20.x.x npm -v装完之后一定要node -v校验。我见过有人nvm install 20成功了但当前 shell 还是指向系统自带的 Node 18结果 Claude Code 装上了却跑不起来。nvm use 20之后如果新开终端又变回去记得nvm alias default 20。Windows 用户直接去 Node.js 官网下载 LTS 安装包选 20.x 那一栏。热搜里的node.js官网下载openclaw、node.js lts下载、node.js下载说的都是这个。安装时勾选“Add to PATH”装完在 PowerShell 里node -v验证。4.2 Claude Code 与 Codex 的安装顺序运行时搞定后装 CLI。顺序上我建议先装 Claude Code再装 Codex。原因是 Claude Code 的安装脚本会顺带检查一些全局依赖先装它能把基础环境铺好。# 安装 Claude Code npm install -g anthropic-ai/claude-code # 安装 Codex npm install -g openai/codex装完分别跑claude --version和codex --version。如果报command not found八成是 npm 全局 bin 目录不在 PATH 里。用npm config get prefix看一下全局目录把它加到 PATH。热搜里的claude code安装、claude code下载安装、codex安装、codex安装教程、codex安装包指向的都是这一步。codex安装 windows桌面版则是另一条路径——Codex 有桌面版但 openrig 这套编排主要针对 CLI桌面版的环境变量注入方式不一样混用容易乱。我的建议是要么全 CLI要么全桌面别混。4.3 代理服务的启动与验证openrig 的代理是整套环境的心脏。启动前先确认 YAML 里的listen端口没被占用。8787 是个常用端口如果被占换成 8790 之类。# 假设 openrig 的代理启动命令是 openrig proxy openrig proxy --config ./openrig.yaml # 另开一个终端验证代理是否活着 curl -s http://127.0.0.1:8787/health健康检查返回 200 就说明代理起来了。然后分别测两条路由# 测 Codex 路由 curl -s -X POST http://127.0.0.1:8787/v1/responses \ -H Content-Type: application/json \ -d {model:gpt-5.6-sol,input:ping} # 测 Claude 路由 curl -s -X POST http://127.0.0.1:8787/v1/messages \ -H Content-Type: application/json \ -d {model:claude-sonnet,messages:[{role:user,content:ping}]}如果 Codex 那条返回model is not supported回去检查modelMap有没有配对。如果返回连接超时检查target指向的后端服务是否在跑。这一步是排查cc switch local proxy failed类问题的标准动作先测代理再测 CLI能把问题范围缩小一半。4.4 在 VS Code 里接入 Claude Code热搜里vscode配置claude code、vscode接入claude code、claude code for vs code问的人很多。Claude Code 有官方 VS Code 扩展装完之后需要在设置里指定 CLI 路径和代理地址。关键配置项是claude-code.baseUrl把它指向 openrig 代理的地址http://127.0.0.1:8787这样 VS Code 里的 Claude Code 和终端里的走同一套代理和模型映射行为一致。如果你在 VS Code 里遇到your organization has disabled claude subscription access for claude code这类提示那是账号层面的策略限制不是环境问题。openrig 能解决的是“环境跑不起来”解决不了“账号没权限”。这种情况要么换账号要么走第三方 API 的 profile。5. 常见问题与排查技巧实录5.1 代理转发失败的三层排查法遇到cc switch local proxy failed while handling codex endpoint /responses我按三层排查层级检查项典型现象处理方式网络层代理端口是否监听curl 健康检查无响应检查 listen 端口占用重启代理路由层路径是否匹配404 或 route not found补全 routes确认 /v1/responses 存在模型层模型名是否被后端支持model is not supported配置 modelMap 做别名替换三层里最容易忽略的是路由层。很多人只配了/v1/chat/completions因为大部分教程都写这个路径但 Codex 用的是/v1/responses。这两个路径在 OpenAI 的 API 体系里是不同的端点代理必须分别处理。5.2 Node 版本相关的报错速查error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这类报错本质是你指定的版本号不存在。Node.js 的版本号是主版本.次版本.补丁版本24.21.0 如果还没发布nvm 或官网都找不到。解决办法是去 Node.js 官网看当前 LTS 的实际版本号或者直接用nvm install --lts让 nvm 自己选。另一个坑是npm install -g时权限不足。Linux 上如果 npm 全局目录是/usr/local普通用户没写权限。要么用sudo不推荐容易把全局目录搞乱要么把 npm prefix 改到用户目录npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH改完之后重新装 CLI就不会再报权限错误。5.3 本地模型接入的注意事项claude code 调用lmstudio的本地模型这个场景核心是把 LM Studio 的本地 endpoint 暴露成 OpenAI 兼容接口。LM Studio 默认监听http://127.0.0.1:1234/v1在 openrig 的 profile 里把baseUrl指过去就行。但有两个坑第一LM Studio 的模型名和 Claude/Codex 期望的模型名对不上必须走modelMap第二本地模型的响应速度比云端慢timeoutMs要调大否则长回复会被代理截断。提示本地模型跑大上下文时显存吃紧建议在 LM Studio 里把 context length 设成 8k 或 16k别一上来就 128k否则加载都加载不起来。5.4 第三方 API 接入的密钥管理第三方api使用技巧、codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型这些需求共同点是密钥管理。我的做法是YAML 里只写${VAR}占位符真实密钥放在~/.openrig/env文件里启动代理前source一下。这个 env 文件加进.gitignore永远不进版本库。# ~/.openrig/env export CLAUDE_KEYsk-xxxx export CODEX_KEYsk-yyyy export DEEPSEEK_KEYsk-zzzz启动脚本里先source ~/.openrig/env再openrig proxy。这样换机器时只需要重新填 env 文件YAML 配置可以原样复制。6. 我在实际使用中总结的几条经验openrig 这套东西跑顺之后最大的感受是AI 编码工具的痛点从来不在模型而在环境。模型能力再强代理转发挂了你就是用不了。所以我把大部分精力花在了代理层的稳定性和可观测性上——给代理加日志、加健康检查、加请求耗时统计比反复换模型有用得多。另一个体会是YAML 配置不要一次写太满。我一开始把所有能想到的 profile 都写进去结果配置文件两百多行改一个参数要翻半天。后来改成“基础配置 按需 profile”主文件只留 runtime、agents、proxy 三段具体模型映射放到单独的profiles/目录下按文件加载维护起来清爽很多。最后分享一个小技巧openrig 的代理日志里把每个请求的model、target、status、durationMs打成一行 JSON然后用jq过滤。排查model is not supported时cat proxy.log | jq select(.status ! 200)一眼就能看出是哪个模型、哪条路由出的问题。这个习惯帮我省掉了大量翻日志的时间。