1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“装配好的整套装置”比如一台矿机的整机、一套测试台架、一组调试工具链。把它放到当下 AI 编程助手满天飞的环境里openrig大概率指的是“一套开放的、可自由拼装的 AI 编码工具装配方案”。结合热搜词里高频出现的claude code、codex、yaml、node.js我基本可以判断这是一个围绕命令行 AI 编码助手做本地化装配、配置与调度的实践方向。为什么会有这个需求因为现在的情况是claude code和codex这类 CLI 工具各自为政安装方式不同、配置文件格式不同、模型接入方式不同。你想在 VS Code 里用一套在终端里用另一套再想接个本地模型或者第三方 API配置就散落在四五个地方。openrig要做的就是把这些零散的东西用一套统一的思路“装配”起来让node.js环境、yaml配置、CLI 工具、编辑器插件各就各位而不是每次换机器都从头折腾一遍。这篇文章适合谁看如果你正在被claude code 安装、codex 安装教程、node.js 安装这些关键词反复折磨或者你已经装好了但不知道怎么把yaml配置和实际工具链串起来那这篇内容就是写给你的。我会从环境底座开始一路讲到配置装配、模型接入、常见报错排查尽量把每一步的“为什么”也讲清楚而不是只丢一堆命令让你抄。需要先说明一点openrig目前没有官方统一文档下面的内容是我基于热搜词反映出的真实使用场景结合claude code、codex、node.js、yaml这些工具的通用实践整理出来的装配思路。你可以把它当成一套可复现的参考方案具体细节按你手头的版本微调。2. 装配之前先把底座打牢node.js 与包管理器的选择2.1 为什么 node.js 版本是第一个坑热搜里有一条特别扎眼error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错说明有人试图安装一个还不存在的 node.js 版本。claude code和codex这类 CLI 工具绝大多数是基于 node.js 生态分发的它们对 node 版本有明确的区间要求。版本太低语法不支持版本太高某些原生依赖还没编译好。所以装配的第一步不是急着装工具而是先把 node 版本锁定在一个“被验证过”的区间。我的建议是直接用 LTS 版本。热搜里也出现了node.js lts下载说明不少人已经意识到 LTS 的稳定性。截至我写这篇内容时node.js 20.x 和 22.x 的 LTS 是兼容性最好的选择。不要盲目追最新的大版本尤其是看到24.x这种还没正式发布的编号时先确认它是不是真的存在。安装方式上Windows 用户直接去 node.js 官网下载 LTS 的 msi 安装包最省事macOS 和 Linux 用户我更推荐用版本管理工具比如nvm或fnm。原因很简单你不可能只用一个 node 版本。今天跑claude code要 20.x明天跑另一个工具要 18.x没有版本管理器你就得反复卸载重装。# 以 fnm 为例安装后锁定 LTS fnm install --lts fnm use --lts node -v npm -v装完之后一定要验证node -v和npm -v都能正常输出。如果npm报错多半是环境变量没配好或者安装过程中权限不足。Windows 上还有一种情况是之前装过旧版本残留的路径和新版本冲突这时候去“应用和功能”里把旧的 node.js 卸载干净再重装。2.2 包管理器npm、pnpm 还是 yarnclaude code和codex的安装命令通常以npm install -g开头所以npm是必须能用的。但如果你后续要在一个项目里同时管理多个 AI 工具的依赖pnpm会更省磁盘空间安装速度也更快。不过对于全局 CLI 工具来说npm的全局安装机制最成熟出问题的概率最低。我的做法是全局工具用npm项目内依赖用pnpm两者互不干扰。这里有个细节值得注意全局安装的 CLI 工具其可执行文件会被放到 npm 的全局 bin 目录。如果这个目录不在系统的 PATH 里你装完了也敲不出命令。可以用npm config get prefix查看全局目录然后确认它下面的binWindows 是根目录在 PATH 中。2.3 网络与镜像安装慢不等于装不上热搜里node.js官网下载和node.js下载同时出现说明很多人在下载环节就卡住了。npm 官方源在国内访问有时会很慢这时候可以临时切换镜像源。但要注意切换镜像源只影响下载速度不影响工具本身的功能。如果你用的是公司网络可能还需要配置代理才能访问外部源这部分按你所在环境的规范来操作即可。# 查看当前源 npm config get registry # 临时使用镜像源安装 npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com装完之后建议把源切回官方避免后续安装其他包时出现版本不一致的问题。3. claude code 与 codex 的安装路径差异3.1 claude code 安装全局装还是项目内装claude code的安装方式在不同平台上略有差异。热搜里出现了claude code安装、安装claude code、claude code下载、claude code windows、ubuntu配置claude code说明 Windows 和 Ubuntu 是两个主要的战场。通用的安装命令是通过 npm 全局安装npm install -g anthropic-ai/claude-code装完之后在终端输入claude应该能看到交互界面。如果提示命令找不到回到上一节检查 PATH。Windows 用户如果用的是 PowerShell可能还需要确认执行策略没有阻止脚本运行。claude code有一个很实用的能力是直接执行终端命令热搜里claude code如何直接执行终端命令就是在问这个。它的工作方式是你用自然语言描述意图它生成命令并请求你确认后执行。这个确认环节很重要不要图省事把确认关掉否则一条误生成的删除命令就可能造成不可逆的后果。3.2 codex 安装注意组织设置与模型支持codex的安装同样走 npm 路线但热搜里出现了两个很具体的报错codex无法加载组织设置和the gpt-5.6-sol model is not supported when using codex with a。这两个问题指向同一个根源codex的模型接入是受配置约束的不是你想用哪个模型就能用哪个。codex无法加载组织设置通常发生在登录环节。codex需要读取你的账户或组织配置来决定可用模型和权限。如果网络请求被拦截或者本地缓存的凭证过期就会报这个错。处理办法是先退出登录清理本地配置目录再重新登录。配置目录一般在用户主目录下的隐藏文件夹里具体路径因版本而异可以用codex --help查看是否有config相关子命令。the gpt-5.6-sol model is not supported这个报错更有意思。它说明有人在配置里指定了一个不被当前codex版本支持的模型名。模型名不是随便写的必须和工具内部维护的模型列表匹配。遇到这种报错第一反应应该是去查当前版本的文档确认支持的模型标识而不是反复重试同一个名字。3.3 两个工具能共存吗可以而且我建议共存。claude code和codex的定位有重叠但不完全一样。claude code在终端命令执行和文件操作上更直接codex在某些代码生成场景下有它的优势。两者都通过 npm 全局安装命令名不同配置文件也各自独立不会互相覆盖。唯一需要注意的是别把两者的 API 密钥或登录凭证搞混。4. yaml 配置openrig 装配思路的核心载体4.1 为什么是 yaml 而不是 json热搜里yaml、yaml文件、yaml安装、yolov10 yaml文件怎么创建、rstudio的yaml在哪里混在一起说明 yaml 这个格式在很多领域都被使用。在 AI 编码工具的语境下yaml 通常用来描述模型接入配置、工具链参数、项目级设置。相比 jsonyaml 的优势是支持注释、层级更直观、手写更友好。你可以在配置里写清楚每一段是干什么的三个月后回来看还能看懂。yaml安装这个搜索词其实有点误导。yaml 本身是一种数据格式不是需要单独安装的软件。你真正需要的是解析 yaml 的库比如 node.js 里的js-yaml。如果你在项目里要用 yaml装的是解析库不是 yaml 本身。npm install js-yaml4.2 一份可参考的模型接入配置结构下面这份 yaml 结构是我在实际装配中常用的模板用来描述多个模型端点的接入信息。字段名你可以按自己使用的工具调整但结构思路是通用的# openrig 模型接入配置示例 version: 1 default_provider: local providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - name: local-model context_window: 8192 max_tokens: 2048 remote: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${API_KEY_FROM_ENV} models: - name: remote-model context_window: 128000 max_tokens: 4096 routing: default: local rules: - match: long-context provider: remote这份配置里有几个设计点值得解释。第一api_key用环境变量占位不要把密钥硬编码进文件否则一旦这个文件被提交到代码仓库密钥就泄露了。第二routing段落定义了路由规则让不同任务走不同模型端点这是openrig装配思路里很关键的一环——不是所有任务都需要最强的模型简单任务走本地端点又快又省。第三context_window和max_tokens显式声明避免工具按默认值去猜猜错了就会在长文本场景下截断。4.3 yaml 缩进与常见语法错误yaml 最坑的地方是缩进。它不允许用 Tab只能用空格而且同一层级的缩进必须完全一致。我见过太多次因为复制粘贴导致缩进混用解析器直接报mapping values are not allowed here。排查这种错误没有捷径就是打开编辑器的“显示空白字符”功能把 Tab 全部替换成两个空格。另一个常见错误是冒号后面没加空格。key:value在 yaml 里不是合法的键值对必须是key: value。这个细节在写配置时很容易忽略尤其是从 json 转过来的时候。提示写完 yaml 后用node -e require(js-yaml).load(require(fs).readFileSync(config.yaml,utf8))快速验证语法比等到工具报错再回头查要高效得多。5. 把工具接进编辑器VS Code 配置的取舍5.1 插件装哪个不装哪个热搜里vscode配置claude code、claude code for vs code、vscode接入claude code、vs code使用方法集中出现说明编辑器集成是刚需。VS Code 的插件市场里同类型插件很多我的原则是只装官方或明确维护活跃的。装太多同功能插件会互相抢快捷键、抢终端控制权最后哪个都用不顺。claude code的 VS Code 集成方式通常有两种一种是通过官方插件在编辑器内提供侧边栏对话另一种是直接在 VS Code 的集成终端里运行 CLI。两种方式不冲突我一般两个都留着写代码时用侧边栏需要执行复杂命令时切到终端。5.2 终端环境变量的坑VS Code 在 Windows 上默认可能用 PowerShell而你在系统终端里配置的环境变量VS Code 的集成终端不一定能读到。表现就是在外部终端里claude能跑在 VS Code 里就提示找不到命令或者读不到 API 密钥。解决办法是在 VS Code 的设置里明确指定终端 shell或者把环境变量写进 VS Code 能读取的配置文件里。macOS 上从 Finder 启动 VS Code 时它不会加载你 shell 的配置文件所以 PATH 里的自定义路径可能缺失。这种情况要么从终端用code .启动 VS Code要么在 VS Code 设置里手动补全 PATH。5.3 本地模型接入编辑器的实际体验热搜里claude code 调用lmstudio的本地模型是一个很具体的需求。把本地模型接进编辑器最大的好处是隐私和离线可用代价是响应速度和上下文长度通常不如云端。实际配置时关键是确认本地模型服务暴露的是 OpenAI 兼容接口然后在 yaml 里把base_url指向本地端口。如果连接失败先确认服务是否在运行再确认端口有没有被防火墙拦截。本地模型的上下文窗口往往偏小配置里如果写了 128000 但模型实际只支持 8192工具可能会在超出部分直接报错或静默截断。所以context_window一定要按模型真实能力填写宁可写小一点。6. 报错排查从 cc switch 到模型不支持6.1 cc switch local proxy failed 的排查链路热搜里有一条很长的报错cc switch local proxy failed while handling codex endpoint /responses。这个报错涉及三个层面cc switch这个切换工具、本地代理、以及codex的/responses端点。排查顺序应该是从外到内。第一步确认cc switch本身是否正常运行。它是一个用来在多个模型配置之间切换的工具如果它自己启动失败后面的代理和端点都无从谈起。第二步确认本地代理端口是否被占用。代理工具通常会监听一个本地端口如果这个端口已经被其他程序占用代理就起不来。用netstat或lsof查一下端口占用情况。第三步确认codex的端点路径是否正确。/responses是特定 API 规范的路径如果你的代理配置里路径写错了请求就会 404。6.2 模型不支持报错的通用处理思路前面提到的the gpt-5.6-sol model is not supported和your organization has disabled claude subscription access属于同一类问题配置里声明的能力当前账户或当前工具版本不具备。处理这类问题的通用思路是报错类型可能原因处理方向模型不支持模型名拼写错误或版本不匹配查当前版本文档确认模型标识组织设置无法加载登录凭证过期或网络拦截退出重登清理本地缓存订阅访问被禁用账户权限或订阅状态问题确认账户状态检查组织策略代理处理失败端口占用或路径配置错误查端口占用核对端点路径这张表里的每一行我都实际遇到过。最容易被忽略的是“模型名拼写错误”因为报错信息不会告诉你正确的名字是什么只会说你不支持。这时候去翻工具的更新日志或者--help输出往往能找到当前支持的模型列表。6.3 安装类报错的快速定位error installing 24.21.0这类报错核心是版本不存在。node.js 的版本号是有严格发布流程的偶数大版本是 LTS奇数大版本是过渡版。24.21.0如果还没发布你指定它当然装不上。解决办法是换成当前实际存在的 LTS 版本。用fnm ls-remote或nvm ls-remote可以列出所有可安装的版本从列表里选一个而不是凭记忆写版本号。7. 装配完成后的验证与日常维护7.1 一套最小验证流程装完 node.js、claude code、codex、配好 yaml 之后不要急着上复杂项目。先用一个最小流程验证整条链路是通的node -v确认 node 可用claude --version确认 claude code 可执行codex --version确认 codex 可执行用 yaml 解析库加载你的配置文件确认语法无误在 VS Code 集成终端里重复第 2、3 步确认编辑器环境一致发一条最简单的对话请求确认模型端点能返回结果这六步走完基本能覆盖 90% 的装配问题。剩下的 10% 通常是特定模型或特定网络环境导致的需要单独排查。7.2 配置文件该不该进版本控制我的做法是配置模板进版本控制实际配置不进。模板里用占位符代替密钥和本地路径实际配置放在.gitignore里。这样团队协作时大家共享结构但各自的密钥和本地端点互不干扰。如果团队需要统一模型路由策略可以把routing段落单独抽出来共享因为它不包含敏感信息。7.3 版本升级的节奏claude code和codex都在快速迭代升级频率很高。我的建议是不要每次发版就升而是固定一个节奏比如每两周升一次升级前先看更新日志里有没有破坏性变更。升级命令很简单npm update -g anthropic-ai/claude-code npm update -g openai/codex升级后如果出现之前能用的配置突然报错第一反应是回滚到上一个版本而不是花几个小时去适配新版本。全局安装的工具回滚很方便指定版本号重装即可。npm install -g anthropic-ai/claude-code1.0.07.4 我踩过的几个真实坑第一个坑是环境变量在 GUI 和终端之间不一致。我在终端里配好了 API 密钥结果 VS Code 从图标启动时读不到排查了半天才发现是启动方式的问题。第二个坑是 yaml 缩进混用复制了一段配置进来看起来对齐了实际上有的是 Tab 有的是空格解析器直接罢工。第三个坑是本地模型端口冲突代理工具和本地模型服务抢同一个端口表现是时好时坏最后用lsof才定位到。这些坑的共同点是报错信息不会直接告诉你原因需要你顺着链路一层层查。所以装配openrig这类工具链时养成“每装一个组件就验证一次”的习惯比全部装完再统一调试要省时间得多。8. 关于 openrig 装配思路的一点个人体会openrig这个词本身没有官方定义但它精准地描述了一种需求把开放的 AI 编码工具装配成一套顺手的装置。这套装置的核心不是某一个工具而是工具之间的衔接方式——node.js 提供运行时底座yaml 提供配置载体claude code和codex提供能力VS Code 提供交互界面本地模型和远程 API 提供算力来源。任何一环出问题整条链路都会卡住。我在实际装配中最大的体会是配置的清晰度比工具的先进性更重要。一份注释完整、结构清晰的 yaml 配置能让你在换机器、换模型、换工具版本时快速定位问题。相反如果配置是东拼西凑来的每次报错都要从头猜。所以花时间把配置整理好是这笔投入里回报最高的部分。另外不要追求一次装配到位。工具在变模型在变你的需求也在变。先跑通最小链路再逐步加功能比一开始就搭一个复杂系统要稳得多。