1. 从 openrig 说起一个被名字耽误的本地 AI 编码环境编排工具第一次看到 openrig 这个名字我下意识以为是某种硬件机架或者挖矿相关的项目直到在几个折腾 Claude Code 和 Codex 的群里反复看到有人提到它才意识到这是个跟本地 AI 编码助手环境搭建强相关的东西。简单说openrig 解决的是一个非常具体的痛点当你同时想用 Claude Code、Codex 这类命令行 AI 编码工具又想让它们接入本地模型或者第三方 API 的时候环境配置会变得极其混乱——Node.js 版本冲突、YAML 配置文件散落各处、代理转发规则互相打架、不同工具的环境变量互相覆盖。openrig 的思路就是把这些东西统一编排起来用一份配置管住所有工具的运行环境。我花了大概两周时间在自己的开发机上完整跑了一遍 openrig 的流程中间踩了不少坑也总结出一些文档里不会写的经验。这篇文章适合三类人看第一类是刚接触 Claude Code 或 Codex连 Node.js 都还没装明白的新手第二类是已经在用这些工具但被多环境配置搞得头大的中级用户第三类是想把本地模型接入编码助手但卡在 YAML 配置和代理转发环节的折腾党。不管你属于哪一类我都会从最基础的环境准备讲起把每个环节的为什么说清楚而不是只丢一堆命令让你复制。需要提前说明的是openrig 本身并不是一个官方大厂出品的东西它更像是社区里一群人为了解决共同问题攒出来的编排方案。所以它的配置逻辑带有很强的实用主义色彩——不追求优雅只追求能跑通。理解了这一点后面看到一些看起来有点粗糙的设计时就不会太意外。2. 环境底座Node.js 版本管理与 YAML 配置的底层逻辑2.1 为什么 Node.js 版本是第一个拦路虎Claude Code 和 Codex 这两个工具本质上都是 Node.js 写的命令行程序它们对 Node.js 版本有硬性要求。我在实际安装过程中遇到过最典型的一个报错就是error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个错误的根源在于你用的版本管理工具试图安装一个还不存在的版本号。很多人看到这个报错第一反应是去 Node.js 官网下载最新版但实际上问题出在版本管理器的源没有同步。我的建议是直接用 Node.js LTS 版本不要追最新。截至我写这篇文章的时候Node.js 20.x 的 LTS 版本对 Claude Code 和 Codex 的兼容性最好。安装方式上Windows 用户直接去 Node.js 官网下载 LTS 安装包最省事Ubuntu 用户我强烈建议用 nvm 而不是 apt 自带的版本因为 apt 源里的 Node.js 版本往往偏旧而且升级麻烦。# Ubuntu 下用 nvm 安装 Node.js LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v这里有个细节值得展开说为什么我不推荐用系统包管理器装 Node.js因为 Claude Code 和 Codex 在运行时会调用一些全局 npm 包如果你用 apt 装的 Node.js全局包的安装路径会跟 nvm 管理的路径冲突导致command not found或者版本错乱。我一开始就是图省事用 apt 装的结果 Codex 死活找不到自己依赖的模块排查了两个小时才发现是路径问题。注意如果你之前用 apt 或 brew 装过 Node.js建议先彻底卸载再装 nvm否则残留的全局包会干扰新环境。卸载命令因系统而异Ubuntu 下可以用sudo apt remove nodejs npm然后手动清理/usr/lib/node_modules目录。2.2 YAML 配置文件到底在配什么openrig 的核心配置载体是 YAML 文件。很多人对 YAML 的认知停留在比 JSON 好写一点的层面但在 openrig 这个场景里YAML 承担的是整个环境的声明式描述——你用什么模型、走什么端口、环境变量怎么注入、不同工具之间怎么隔离全部写在一个或多个 YAML 里。YAML 的语法本身不复杂缩进用空格不用 Tab键值对用冒号分隔列表用短横线。但 openrig 的配置文件里有一些容易踩坑的地方。比如字符串值如果包含特殊字符像 URL 里的冒号必须用引号包起来否则解析会出错。我第一次写配置的时候把一个 API 地址直接裸写进去结果 YAML 解析器把冒号后面的部分当成了新的键值对报了一堆莫名其妙的错。# openrig 配置示例结构 providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed remote: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${API_KEY_ENV} tools: claude-code: provider: local model: qwen2.5-coder codex: provider: remote model: deepseek-coder上面这个结构是我根据实际使用习惯简化过的核心思想是把模型提供方和使用工具解耦。这样你换模型的时候只需要改 providers 部分不用动 tools 的配置。这个设计思路在 openrig 里很常见理解了这个分层逻辑后面看任何配置都不会晕。2.3 环境变量注入的时机问题openrig 在启动工具之前会读取 YAML 里的环境变量配置然后注入到子进程里。这里有个时机问题很多人会忽略如果你在 shell 里已经 export 了同名的环境变量openrig 的注入行为取决于它的实现——有些版本是覆盖有些是跳过。我实测下来最稳妥的做法是不要在 shell 里预设这些变量全部交给 openrig 的 YAML 管理避免出现我明明改了配置但没生效的情况。另外API key 这类敏感信息不要直接写在 YAML 里。openrig 支持${VAR_NAME}的语法从系统环境变量读取把真正的密钥放在 shell 的 profile 文件或者系统的密钥管理里YAML 里只写引用。这样配置文件可以安全地提交到 git 或者分享给别人。3. Claude Code 与 Codex 的接入实操从安装到跑通第一条命令3.1 Claude Code 的安装与首次配置Claude Code 的安装本身不复杂npm 全局装就行npm install -g anthropic-ai/claude-code但装完之后第一次运行才是真正的考验。如果你直接跑claude命令它会引导你登录。这里有个分岔路如果你用的是官方订阅直接走登录流程就行如果你想接入本地模型或者第三方 API就需要在 openrig 的配置里指定 provider然后通过环境变量告诉 Claude Code 去哪里找模型。我试过在 VS Code 里配置 Claude Code也试过在纯终端里用两种方式的体验差别挺大。VS Code 里的优势是能直接看到文件改动终端里的优势是启动快、资源占用低。如果你主要做的是大范围代码重构VS Code 插件模式更合适如果只是偶尔问几个问题、跑个脚本终端模式足够了。提示Claude Code 在 Windows 上的原生支持不如 macOS 和 Linux 好如果你在 Windows 上遇到奇怪的路径问题可以考虑在 WSL2 里跑体验会顺滑很多。我自己在 Windows 上折腾了一下午没搞定的事情换到 WSL2 里十分钟就跑通了。3.2 Codex 的安装与常见报错处理Codex 的安装方式跟 Claude Code 类似但它在配置上更挑剔一些。我遇到过最烦人的一个报错是codex is ignoring 1 unrecognized configuration setting. check for typos or d这个报错的意思是配置文件里有一个它不认识的键。问题在于 Codex 的报错信息不会告诉你具体是哪个键有问题你得自己一个个排查。我的排查方法是把配置文件里的键逐个注释掉二分法定位。虽然笨但有效。后来我发现这个报错最常见的原因是 YAML 里的键名大小写不对或者用了 Codex 不支持的配置项。Codex 的配置项命名风格是 kebab-case比如api-key而不是apiKey这一点跟很多人的直觉相反。另一个高频问题是codex无法加载组织设置这个通常出现在你用了某个组织的 API 端点但权限没配好的情况下。如果你只是个人使用建议直接用个人 API key不要走组织配置能省掉很多麻烦。3.3 用 openrig 统一管理多工具环境单独装 Claude Code 和 Codex 其实不难难的是让它们共存且互不干扰。我一开始的做法是给每个工具写一个 shell 脚本脚本里 export 一堆环境变量然后启动工具。这个方案能用但维护起来很痛苦——改一个模型配置要改好几个脚本而且很容易忘记某个脚本没更新。openrig 的价值就在这里体现出来了。它把环境变量的注入、provider 的选择、模型的指定全部收拢到 YAML 里启动工具的时候只需要告诉 openrig 你要跑哪个工具剩下的它来处理。我现在的做法是在项目根目录放一个openrig.yaml里面定义好这个项目需要的所有工具配置换项目的时候换一份 YAML 就行。# 用 openrig 启动 Claude Code openrig run claude-code # 用 openrig 启动 Codex openrig run codex这两条命令背后openrig 做了这些事情读取 YAML 配置、解析 provider 和 model、注入环境变量、启动对应的工具进程、把工具的输出转发到当前终端。理解了这个流程你就能明白为什么有时候工具报错说找不到 API key——大概率是 YAML 里的环境变量引用写错了或者对应的系统环境变量没设置。4. 本地模型接入与代理转发的那些坑4.1 为什么要在本地跑模型把 Claude Code 或 Codex 接到本地模型上最直接的好处是省钱和隐私。本地模型不消耗 API 额度代码不出本机。但代价也很明显本地模型的代码能力通常不如云端大模型尤其是复杂推理和长上下文场景。我自己的用法是混合模式——日常的代码补全和简单问答走本地模型遇到复杂问题再切到云端。本地模型的部署方式有很多种我用的是 LM Studio因为它对 OpenAI 兼容 API 的支持比较好配置简单。启动 LM Studio 的本地服务器后它会监听一个端口默认 1234提供/v1/chat/completions接口。openrig 的 YAML 里把 provider 的 base_url 指向这个地址就行。注意LM Studio 的本地服务器默认只监听 127.0.0.1如果你在 WSL2 里跑 Claude Code 而 LM Studio 跑在 Windows 宿主机上需要让 LM Studio 监听 0.0.0.0否则 WSL2 里访问不到。这个坑我踩过排查了半天才发现是网络隔离的问题。4.2 代理转发失败的典型场景热词里有一个cc switch local proxy failed while handling codex endpoint /responses这个报错我太熟悉了。它的本质是代理层在转发 Codex 的请求时遇到了它不认识的 endpoint 或者请求格式。Codex 用的 API 格式跟标准的 OpenAI 格式有一些差异尤其是/responses这个端点很多代理工具默认不支持。解决思路有两个一是换一个支持 Codex 格式的代理工具二是自己写一层转换。我选的是第一种因为自己写转换层的维护成本太高Codex 的 API 格式还在变。选代理工具的时候重点看它是否明确声明支持 Codex 的 endpoint不要只看它说支持 OpenAI 兼容就以为万事大吉。另一个常见问题是代理转发时的超时设置。本地模型的首 token 延迟可能很高如果代理的默认超时是 30 秒很容易在模型还没开始输出的时候就断开连接。我一般会把代理的超时设到 120 秒以上给本地模型足够的预热时间。4.3 第三方 API 接入的注意事项用第三方 API 接入 Claude Code 或 Codex 的时候有几个点需要特别注意。第一是 API 的兼容性不是所有声称OpenAI 兼容的 API 都真的兼容有些只是在基础对话接口上兼容一到工具调用或者流式输出就出问题。第二是速率限制第三方 API 的限流策略往往比官方严格如果你用 Claude Code 做大批量代码分析很容易触发限流。我的做法是在 openrig 的配置里给每个 provider 设置独立的并发限制和重试策略。这样即使某个 provider 被限流了也不会影响其他工具的正常使用。重试策略上我建议用指数退避第一次重试等 1 秒第二次等 2 秒第三次等 4 秒最多重试 3 次。这个策略在大多数限流场景下都能自动恢复。5. 常见问题速查与排查思路5.1 安装阶段的报错对照表报错信息可能原因解决方法node.js v24.21.0 is not yet released版本管理器源未同步或指定了不存在的版本改用 LTS 版本更新版本管理器command not found: claudenpm 全局路径未加入 PATH检查 npm prefix把全局 bin 目录加入 PATHEACCES permission denied全局安装权限不足用 nvm 管理 Node.js避免 sudo npm installcodex is ignoring unrecognized configuration settingYAML 键名拼写错误或大小写不对逐个注释排查确认用 kebab-case无法加载组织设置组织 API 端点权限配置问题改用个人 API key这张表里的每一条都是我实际遇到过的不是从文档里抄的。其中EACCES permission denied这个坑最典型很多人第一反应是加 sudo但 sudo npm install 会导致后续一系列权限问题正确的做法是用 nvm 或者修改 npm 的全局目录。5.2 运行阶段的排查思路运行阶段的报错往往比安装阶段更难排查因为涉及的因素更多。我的排查顺序是这样的先确认 Node.js 版本对不对再确认环境变量有没有正确注入然后确认网络能不能通到目标 API最后确认 API 返回的内容格式对不对。这个顺序的逻辑是从简单到复杂。Node.js 版本问题一眼就能看出来环境变量问题可以通过printenv快速确认网络问题用 curl 测一下就知道只有 API 返回格式的问题需要抓包或者看日志。按这个顺序排查大部分问题都能在五分钟内定位。提示openrig 的日志默认输出到 stderr如果你在脚本里调用它记得把 stderr 也重定向到日志文件否则报错信息会丢失。我一开始只重定向了 stdout结果出问题的时候什么都看不到白白浪费了很多时间。5.3 我踩过的三个印象最深的坑第一个坑是 YAML 的缩进。我用编辑器写配置的时候编辑器自动把 Tab 转成了空格但转得不彻底混用了 Tab 和空格。YAML 解析器对这种混合缩进的处理方式不一致有的报错有的静默解析成错误的结构。后来我养成了习惯写完 YAML 一定用yamllint检查一遍。第二个坑是环境变量的作用域。我在 shell 里 export 了一个 API key然后在 openrig 的 YAML 里引用了它但启动工具的时候发现 key 是空的。排查后发现是因为我用sudo启动的 openrig而 sudo 默认不继承当前用户的环境变量。这个坑的教训是尽量不要用 sudo 跑 openrig如果非要跑用sudo -E保留环境变量。第三个坑是本地模型的上下文长度。我一开始用了一个上下文只有 4K 的本地模型结果 Claude Code 在处理稍微大一点的文件时就报错说超出上下文限制。换了一个 32K 上下文的模型后问题解决。这个坑的教训是本地模型的上下文长度直接决定了它能处理多大的代码文件选模型的时候一定要看这个参数。6. 一些让环境更稳的配置技巧6.1 用 profile 隔离不同项目的配置如果你同时维护多个项目每个项目对模型和工具的需求可能不一样。我的做法是在每个项目的根目录放一个.openrig/目录里面放这个项目专属的 YAML 配置。openrig 启动的时候会优先读取当前目录下的配置找不到再往上找。这样不同项目之间完全隔离不会互相干扰。这个技巧的关键是理解 openrig 的配置查找顺序。它跟 git 找.gitignore的逻辑类似从当前目录往上逐级查找找到第一个就停。所以如果你在父目录放了一个通用配置在子目录放了一个项目专属配置子目录的配置会覆盖父目录的。6.2 给常用命令起别名openrig 的命令不算长但每天敲几十遍也烦。我在.bashrc里加了几个别名alias ocopenrig run claude-code alias oxopenrig run codex alias olopenrig list这样启动 Claude Code 只需要敲oc两个字母。别小看这点效率提升一天下来能省不少时间。而且别名可以带参数比如alias ocropenrig run claude-code --resume用来恢复上次的会话。6.3 定期更新但不要追新Claude Code 和 Codex 的更新频率很高几乎每周都有新版本。我的策略是每个月更新一次不追最新的版本。原因是新版本有时候会引入不兼容的配置变更如果你正在赶项目突然因为更新导致环境跑不起来会很耽误事。更新之前先看一下 changelog确认没有破坏性变更再动手。更新的时候我建议先把当前的 YAML 配置备份一份更新完如果出问题可以快速回滚。回滚的方式很简单把备份的 YAML 覆盖回去然后把工具降级到之前的版本就行。npm 的降级命令是npm install -g anthropic-ai/claude-code版本号Codex 类似。6.4 监控资源占用本地模型和 AI 编码工具都是资源大户。我试过同时跑 Claude Code、Codex 和一个本地模型16G 内存的机器直接卡死。后来我养成了习惯跑之前先看一眼内存和 CPU 占用如果本地模型已经吃了 8G 内存就不要再同时跑两个编码工具了。在 Linux 和 macOS 上我一般用htop看资源占用。Windows 上用任务管理器就行。如果你经常遇到卡顿可以考虑给本地模型设置内存上限或者换一个更轻量的模型。代码补全场景其实不需要太大的模型7B 参数左右的模型在补全任务上已经够用了。7. 关于 openrig 这类工具的一些个人看法折腾了这么久我最大的体会是这类编排工具的价值不在于它本身有多强大而在于它把散落各处的配置收拢到了一处。在没有 openrig 之前我的环境变量散落在.bashrc、.zshrc、各个项目的.env文件、以及一堆 shell 脚本里改一个配置要翻好几个地方。有了 openrig 之后至少模型和 provider 相关的配置是集中的。但 openrig 也不是银弹。它的 YAML 配置有一定的学习成本而且因为不是官方出品文档和社区支持都比较有限。遇到问题的时候很多时候得自己看源码或者去群里问。如果你只是偶尔用一下 Claude Code可能不值得为它专门搭一套 openrig 环境。但如果你每天都在用而且同时用好几个工具那花点时间把环境理顺是值得的。另外这类工具的生态变化很快。今天流行的配置方式可能半年后就过时了。所以我的建议是不要过度依赖某一个工具把核心的配置逻辑理解清楚这样即使换工具也能快速迁移。比如理解了 provider 和 model 的分层逻辑换到任何类似的编排工具上都能很快上手。最后分享一个我最近发现的小技巧如果你在 VS Code 里用 Claude Code可以把 openrig 的启动命令配到 VS Code 的 tasks.json 里这样按一个快捷键就能启动整个环境不用切到终端敲命令。具体配置方式是在.vscode/tasks.json里加一个 taskcommand 设为openrigargs 设为[run, claude-code]。这个技巧对经常在编辑器和终端之间切换的人来说能省不少事。