1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的画面是矿机机架、服务器机柜那种“rig”。在开发者圈子里rig 通常指一套组装起来的硬件或软件工作台。把 open 和 rig 拼在一起我的直觉是这是一个把 AI 编程助手Claude Code、Codex 这类 CLI 工具的配置、模型接入、环境依赖打包成一套可复用“工作台”的开源方案。事实也确实往这个方向走——它要解决的核心痛点是当下每个想用命令行 AI 编程助手的人都会撞上的那堵墙环境装不起来、模型接不进去、配置改一次崩一次。我身边不少朋友最近都在折腾 Claude Code 和 Codex。有人卡在 Node.js 版本上有人卡在 YAML 配置的缩进上还有人被“your organization has disabled claude subscription access”这种提示直接劝退。这些问题的共同点是它们跟 AI 能力本身没关系全是环境工程问题。openrig 的价值就在于它试图把这一堆琐碎的、跨平台的、容易出错的配置工作收敛成一套结构化的、可版本管理的方案。这篇文章适合三类人看。第一类是刚听说 Claude Code、Codex想上手但被安装步骤劝退的新手第二类是已经装上了但想接入本地模型比如 LM Studio或者第三方 API 的中级用户第三类是团队里负责给其他人搭环境的人你需要一套能复制、能交接的配置模板。我会从 openrig 的设计思路讲起把 Node.js、YAML、模型接入、常见报错这几块拆开揉碎最后给出一套我自己实测能跑通的完整流程。需要先说明一点openrig 目前并不是一个官方大厂背书的产品它更像社区里一群人把踩坑经验沉淀下来的配置集合。所以我会把“它可能是什么”和“我实际怎么用”分开讲避免你把某个具体实现当成唯一标准。2. 拆解 openrig 的核心设计思路为什么是 YAML Node.js 这套组合2.1 为什么这类工具几乎都绕不开 Node.jsClaude Code、Codex CLI 这些工具绝大多数是用 Node.js 写的或者至少通过 npm 分发。这不是巧合。Node.js 的生态里npm 是全球最大的包管理仓库一个npm install -g就能把命令行工具装到全局跨 Windows、macOS、Linux 的体验相对统一。对于“我要快速让用户装上一个 CLI”这个需求Node.js 是成本最低的选择。但 Node.js 也带来了它自己的麻烦。最典型的就是版本问题。热搜里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available” 就是活生生的例子——某个工具声明它依赖 Node 24.21.0但这个版本根本还没发布或者你的镜像源里没有。这种报错对新手来说是致命的因为你根本不知道是工具的问题还是自己环境的问题。我的经验是不要盲目追最新版 Node.js。LTS长期支持版才是生产环境该用的。截至我写这篇内容时Node.js 20.x 和 22.x 的 LTS 是主流选择。你可以去 Node.js 官网下载 LTS 版本或者用 nvmNode Version Manager来管理多个版本。用 nvm 的好处是当某个工具要求特定版本时你一条命令就能切过去不用卸载重装。# 用 nvm 安装并切换到 Node 20 LTS nvm install 20 nvm use 20 node -v # 确认输出 v20.x.x npm -v提示Windows 用户如果不想折腾 nvm直接去 Node.js 官网下载 LTS 的 .msi 安装包最省事。安装时勾选“Add to PATH”装完打开新的终端窗口验证。2.2 YAML 在 openrig 里扮演什么角色YAML 是 openrig 这类方案的“配置骨架”。为什么不用 JSON因为 JSON 不支持注释写配置的人没法在文件里标注“这一行是干嘛的”。为什么不用 TOMLTOML 在嵌套结构上不如 YAML 直观。YAML 用缩进表达层级人类读起来接近自然语言特别适合写“模型列表”“工具参数”“环境变量”这种结构化配置。但 YAML 也是新手最容易翻车的地方。它的缩进必须用空格不能用 Tab冒号后面必须跟一个空格列表项的短横线后面也要有空格。我见过太多人因为一个 Tab 键排查了半小时。热搜里“yolov10 yaml文件怎么创建”“rstudio的yaml在哪里”这类问题本质上都是同一个困惑YAML 文件该放哪、怎么写才不报错。在 openrig 的语境下YAML 通常用来定义这几类东西模型提供方provider的地址和密钥、每个工具Claude Code / Codex用哪个模型、以及一些运行时参数超时时间、重试次数。一个典型的配置片段长这样providers: - name: local-lmstudio base_url: http://localhost:1234/v1 api_key: not-needed models: - qwen2.5-coder - deepseek-coder tools: claude-code: provider: local-lmstudio model: qwen2.5-coder codex: provider: local-lmstudio model: deepseek-coder这段配置的意思是我本地跑了一个 LM Studio它暴露了 OpenAI 兼容的接口地址是localhost:1234。然后我让 Claude Code 和 Codex 都走这个本地模型。注意api_key那行本地模型通常不校验密钥但很多客户端要求这个字段不能为空所以随便填一个占位符就行。2.3 openrig 想避免的三个坑我把 openrig 的设计目标归纳成三条这也是它区别于“手动一个个装”的地方。第一避免环境漂移。你今天装好的 Node 版本、npm 全局包、配置文件过一个月换台机器就全乱了。openrig 通过把配置和依赖声明集中管理让“换机器”变成“拉代码 跑一条安装命令”。第二避免模型接入的重复劳动。Claude Code 和 Codex 各自有自己的配置方式一个用环境变量一个用配置文件。openrig 试图用统一的 YAML 描述模型来源再由它分发到各个工具。这样你换模型时只改一处。第三避免“组织策略”类报错把人卡死。热搜里 “your organization has disabled claude subscription access for claude code” 和 “codex无法加载组织设置” 都是账号层面的限制。openrig 的思路是让你能方便地切换到第三方 API 或本地模型绕开对单一账号体系的依赖。这一点对国内用户尤其重要因为很多官方订阅在支付和网络层面都有门槛。3. 核心细节解析Node.js、YAML、模型接入的实操要点3.1 Node.js 安装LTS、镜像源与版本锁定安装 Node.js 这件事说简单也简单说坑也多。我按操作系统分开讲。Windows 用户直接去 Node.js 官网下载 LTS 的安装包。安装过程中有一个选项叫“Automatically install the necessary tools”如果你不打算编译原生模块可以不勾省得它去装一堆 Visual Studio 构建工具。装完之后打开 PowerShell 或 CMD输入node -v和npm -v验证。如果提示“不是内部或外部命令”说明 PATH 没配好重新装一遍并确保勾选 Add to PATH。macOS 用户我强烈建议用 Homebrew 或者 nvm。Homebrew 的brew install node装的是最新稳定版但不一定是 LTS。nvm 更灵活# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.zshrc # 或 ~/.bashrc # 安装 LTS nvm install --lts nvm use --ltsLinux 用户尤其是 Ubuntu系统自带的 apt 源里的 Node 版本往往很旧。不要用apt install nodejs用 NodeSource 的源或者 nvm。热搜里“ubuntu配置claude code”“ubuntu 安装claude code”这类需求第一步就是把 Node 搞对。关于镜像源如果你在国内npm 默认源下载速度可能很慢。可以临时或永久切换到国内镜像# 查看当前源 npm config get registry # 切换到国内镜像 npm config set registry https://registry.npmmirror.com注意切换镜像源只影响包下载速度不影响工具功能。但有些企业内网会屏蔽外部源这时候你需要问清楚内网有没有私有 npm 仓库。版本锁定这块openrig 这类方案通常会在项目里放一个.nvmrc文件内容就一行版本号比如20.11.0。这样团队成员只要nvm use就能自动切到正确版本。这个细节很小但能省掉大量“为什么你那边能跑我这边不行”的扯皮。3.2 YAML 配置从“能跑”到“好维护”写 YAML 配置新手最容易犯的错我列一下你对照检查用了 Tab 缩进。YAML 只认空格通常 2 个空格一级。冒号后面没加空格。name:value是错的必须name: value。列表项短横线后没空格。-item是错的必须- item。字符串里有特殊字符没加引号。比如api_key: abc:def会因为多出来的冒号被解析错应该写成api_key: abc:def。布尔值歧义。yes、no、on、off在 YAML 里会被解析成布尔值如果你想要字符串得加引号。我自己的习惯是写完 YAML 先用一个在线校验器或者python -c import yaml; yaml.safe_load(open(config.yaml))过一遍确认语法没问题再拿去用。这个习惯帮我省了无数次“配置看起来没问题但工具就是报错”的时间。关于配置文件放哪不同工具不一样。Claude Code 通常读用户主目录下的配置Codex 可能读项目目录下的配置。openrig 的价值之一就是它帮你把“哪个文件放哪”这件事标准化了。如果你是自己手动配记住一个原则全局配置放主目录项目级配置放项目根目录项目级覆盖全局。3.3 模型接入本地模型与第三方 API 两条路模型接入是 openrig 最核心的功能。我分两条路讲。第一条路是本地模型。热搜里“claude code 调用lmstudio的本地模型”就是这条路。LM Studio 是一个可以在本地跑大模型的桌面应用它启动后会暴露一个 OpenAI 兼容的接口默认地址是http://localhost:1234/v1。你要做的是在 openrig 的 YAML 里把这个地址配上然后让 Claude Code 或 Codex 指向它。本地模型的好处是数据不出本机、不花钱、不怕断网。坏处是对硬件有要求而且小模型的能力跟云端大模型差距明显。我的建议是如果你只是想让 AI 帮你写写脚本、改改配置7B 到 14B 的代码模型够用如果你要它理解大型项目还是得用云端模型。第二条路是第三方 API。热搜里“codex接入deepseek”“使用cc switch 接入 deepseek v4, qwen, glm等模型”都是这个方向。国内有不少模型提供方提供 OpenAI 兼容的接口你只要拿到 base_url 和 api_key就能接进来。配置方式跟本地模型几乎一样只是地址换成对方的域名。这里有个关键点不是所有模型都支持所有工具需要的接口格式。比如 Codex 可能依赖/responses这个端点而某些第三方 API 只实现了/chat/completions。热搜里 “cc switch local proxy failed while handling codex endpoint /responses” 这个报错本质就是代理层没能正确转发或转换这个端点。遇到这种情况你要么换一个兼容性更好的提供方要么在中间加一层转换代理。提示接入第三方 API 时先在终端用 curl 测一下端点通不通再去配工具。这样能把“网络问题”和“配置问题”分开排查。curl http://localhost:1234/v1/models # 如果返回模型列表说明本地服务正常4. 完整实操流程从零搭一套能跑的 openrig 环境4.1 环境准备清单与安装顺序我把整个流程拆成六步顺序很重要因为后面的步骤依赖前面的结果。安装 Node.js LTS用 nvm 或官网安装包。配置 npm 镜像源国内用户。安装 Claude Code 和 Codex 的 CLI 包。准备模型来源本地 LM Studio 或第三方 API。编写 openrig 的 YAML 配置。验证每个工具能否正常调用模型。第一步和第二步前面讲过了。第三步安装命令通常是全局安装npm install -g anthropic-ai/claude-code npm install -g openai/codex包名可能会变以官方文档为准。装完之后用claude --version和codex --version验证。如果提示命令找不到检查 npm 全局 bin 目录有没有在 PATH 里。npm config get prefix可以看到全局安装位置。第四步如果你用 LM Studio打开它下载一个代码模型比如 Qwen2.5-Coder 7B然后在“Local Server”标签页启动服务。确认端口是 1234并且勾选了“OpenAI Compatible API”。如果你用第三方 API去对方控制台拿到 base_url 和 key。4.2 YAML 配置文件的完整写法与参数说明下面是我自己用的一套配置模板你可以直接抄改掉地址和模型名就行。version: 1 providers: - name: lmstudio type: openai-compatible base_url: http://localhost:1234/v1 api_key: lm-studio timeout: 120 models: - qwen2.5-coder-7b-instruct - deepseek-coder-v2 - name: remote-api type: openai-compatible base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} timeout: 60 models: - deepseek-chat - qwen-max tools: claude-code: provider: lmstudio model: qwen2.5-coder-7b-instruct max_tokens: 4096 temperature: 0.2 codex: provider: remote-api model: deepseek-chat max_tokens: 8192 temperature: 0.1几个参数我解释一下。timeout是请求超时时间本地模型推理慢设大一点120 秒比较稳妥。temperature控制输出的随机性写代码场景建议 0.1 到 0.3太高了它会瞎编。max_tokens是单次回复的最大长度设太小会被截断设太大浪费资源。api_key那里用了${REMOTE_API_KEY}这是从环境变量读取的写法避免把密钥硬编码进文件。这个习惯很重要尤其是你要把配置提交到 Git 仓库的时候。注意如果你的 YAML 里要写 Windows 路径反斜杠要转义或者用正斜杠。比如C:\Users\me在 YAML 里可能出问题写成C:/Users/me更安全。4.3 验证与联调怎么确认真的通了配置写完别急着在项目里用。先做最小验证。对 Claude Code你可以直接问它一个简单问题看它有没有走你配的模型。如果它回复的内容风格跟你选的模型一致说明通了。如果报错看错误信息里的端点地址是不是你配的那个。对 Codex类似。如果报 “model is not supported” 这类错说明你配的模型名跟提供方实际支持的模型名对不上。去提供方的模型列表里核对准确名称。我自己的验证顺序是先用 curl 直接打提供方的接口确认网络和密钥没问题再用工具自带的“列出模型”命令确认工具能读到模型列表最后才发一个实际请求。这样分层排查出问题时能快速定位是哪一层的问题。# 第一步curl 测提供方 curl -s http://localhost:1234/v1/models | head -c 500 # 第二步工具侧验证以 Claude Code 为例具体命令以官方为准 claude --list-models4.4 把配置纳入版本管理openrig 的“rig”感很大程度来自它可版本管理。我建议你把 YAML 配置、.nvmrc、以及一个简短的 README 放进 Git 仓库。README 里写清楚需要哪个 Node 版本、怎么装依赖、怎么启动本地模型、怎么设置环境变量。这样别人 clone 下来照着 README 走一遍就能跑起来。密钥不要进仓库。用.env文件或者系统环境变量然后在.gitignore里把.env排除掉。如果团队协作可以用一个.env.example文件列出需要哪些变量但不填真实值。5. 常见问题与排查技巧实录5.1 安装类报错速查报错关键词可能原因解决方向node.js v24.21.0 is not yet released工具声明了不存在的 Node 版本换 LTS 版本或用 nvm 切到可用版本command not found: claudenpm 全局 bin 不在 PATH检查npm config get prefix把 bin 目录加入 PATHEACCES permission denied全局安装权限不足不要用 sudo改用 nvm 管理 Nodenpm install 卡住不动默认源太慢切换国内镜像源安装类问题九成出在 Node 版本和 PATH 上。我的建议是遇到安装报错先node -v和npm -v看版本再which node看路径基本能定位。5.2 模型接入类报错速查报错关键词可能原因解决方向connection refused本地模型服务没启动检查 LM Studio 是否在运行端口是否对401 unauthorizedAPI key 错误或缺失核对 key确认环境变量已加载model is not supported模型名写错用提供方的模型列表核对准确名称/responses endpoint failed提供方不支持该端点换提供方或加转换代理organization has disabled access账号策略限制切换到第三方 API 或本地模型“organization has disabled claude subscription access” 这个报错我单独说一下。它通常出现在你用某个组织账号登录但该组织关闭了 Claude Code 的访问权限。解决办法有两个换一个个人账号或者干脆走第三方 API / 本地模型绕开账号体系。这也是 openrig 这类方案存在的意义之一——它让你对单一账号的依赖降到最低。5.3 我踩过的三个坑第一个坑YAML 里用了 Tab。那次我排查了四十分钟最后用cat -A config.yaml才看到^I字符。现在我写 YAML 第一件事就是确认编辑器把 Tab 转成了空格。第二个坑本地模型端口冲突。LM Studio 默认 1234但我机器上另一个服务占了这个端口导致 Claude Code 连上去后返回的是另一个服务的响应。排查方法是lsof -i :1234看谁在占用。第三个坑环境变量没生效。我在.env里写了 key但工具启动时没加载这个文件。后来改成在 shell 配置里export或者用工具支持的--env-file参数才解决。环境变量的加载顺序是个容易被忽略的细节。5.4 性能与体验优化的小技巧本地模型推理慢这是硬件决定的但你可以通过几个设置改善体验。一是把max_tokens调小让它别生成太长二是用更小的量化模型比如 4-bit 量化版速度会快不少三是把temperature调低减少它“思考”的时间。如果你同时用 Claude Code 和 Codex建议给它们配不同的模型。比如 Claude Code 配一个擅长对话和解释的模型Codex 配一个擅长补全代码的模型。这样各取所长体验更好。还有一点日志要开。很多工具支持--verbose或DEBUG*环境变量。出问题时打开日志能看到它实际请求的地址和参数比猜快得多。6. 关于 openrig 后续可以怎么扩展这套东西搭起来之后能扩展的方向不少。我列几个我自己在用的。一是加一个健康检查脚本。每次开工前跑一下自动检测 Node 版本、模型服务是否在线、配置文件语法是否正确。有问题提前发现别等到写代码写到一半才发现模型连不上。二是把配置模板化。不同项目用不同模型你可以准备几套 YAML用符号链接或者环境变量切换。比如config.local.yaml和config.remote.yaml需要哪个就软链到config.yaml。三是接入更多工具。openrig 的思路不局限于 Claude Code 和 Codex任何读配置、走 OpenAI 兼容接口的 CLI 工具都能纳进来。你只要在 YAML 里加一段tools配置就行。四是做团队分发。把仓库做成模板新成员 clone 下来跑一个make setup或者npm run setup自动装依赖、拉模型、生成配置。这一步做完团队里“环境不一致”的问题基本就消失了。我个人在实际操作中的体会是openrig 这类方案最大的价值不在于它省了多少安装时间而在于它把“环境”这件事从“每个人各自的手艺”变成了“可复制、可审查、可交接的工程资产”。你踩过的坑写进配置和 README 里下一个人就不用再踩。这才是它作为“rig”的真正意义——一个稳固的、开放的工作台而不是一堆散落的命令。 
长河君 · 2026/10/3 14:47:15 · 阅读 1.2k openrig实战：用YAML+Node.js统一管理Claude Code与Codex的模型接入
1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的画面是矿机机架、服务器机柜那种“rig”。在开发者圈子里rig 通常指一套组装起来的硬件或软件工作台。把 open 和 rig 拼在一起我的直觉是这是一个把 AI 编程助手Claude Code、Codex 这类 CLI 工具的配置、模型接入、环境依赖打包成一套可复用“工作台”的开源方案。事实也确实往这个方向走——它要解决的核心痛点是当下每个想用命令行 AI 编程助手的人都会撞上的那堵墙环境装不起来、模型接不进去、配置改一次崩一次。我身边不少朋友最近都在折腾 Claude Code 和 Codex。有人卡在 Node.js 版本上有人卡在 YAML 配置的缩进上还有人被“your organization has disabled claude subscription access”这种提示直接劝退。这些问题的共同点是它们跟 AI 能力本身没关系全是环境工程问题。openrig 的价值就在于它试图把这一堆琐碎的、跨平台的、容易出错的配置工作收敛成一套结构化的、可版本管理的方案。这篇文章适合三类人看。第一类是刚听说 Claude Code、Codex想上手但被安装步骤劝退的新手第二类是已经装上了但想接入本地模型比如 LM Studio或者第三方 API 的中级用户第三类是团队里负责给其他人搭环境的人你需要一套能复制、能交接的配置模板。我会从 openrig 的设计思路讲起把 Node.js、YAML、模型接入、常见报错这几块拆开揉碎最后给出一套我自己实测能跑通的完整流程。需要先说明一点openrig 目前并不是一个官方大厂背书的产品它更像社区里一群人把踩坑经验沉淀下来的配置集合。所以我会把“它可能是什么”和“我实际怎么用”分开讲避免你把某个具体实现当成唯一标准。2. 拆解 openrig 的核心设计思路为什么是 YAML Node.js 这套组合2.1 为什么这类工具几乎都绕不开 Node.jsClaude Code、Codex CLI 这些工具绝大多数是用 Node.js 写的或者至少通过 npm 分发。这不是巧合。Node.js 的生态里npm 是全球最大的包管理仓库一个npm install -g就能把命令行工具装到全局跨 Windows、macOS、Linux 的体验相对统一。对于“我要快速让用户装上一个 CLI”这个需求Node.js 是成本最低的选择。但 Node.js 也带来了它自己的麻烦。最典型的就是版本问题。热搜里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available” 就是活生生的例子——某个工具声明它依赖 Node 24.21.0但这个版本根本还没发布或者你的镜像源里没有。这种报错对新手来说是致命的因为你根本不知道是工具的问题还是自己环境的问题。我的经验是不要盲目追最新版 Node.js。LTS长期支持版才是生产环境该用的。截至我写这篇内容时Node.js 20.x 和 22.x 的 LTS 是主流选择。你可以去 Node.js 官网下载 LTS 版本或者用 nvmNode Version Manager来管理多个版本。用 nvm 的好处是当某个工具要求特定版本时你一条命令就能切过去不用卸载重装。# 用 nvm 安装并切换到 Node 20 LTS nvm install 20 nvm use 20 node -v # 确认输出 v20.x.x npm -v提示Windows 用户如果不想折腾 nvm直接去 Node.js 官网下载 LTS 的 .msi 安装包最省事。安装时勾选“Add to PATH”装完打开新的终端窗口验证。2.2 YAML 在 openrig 里扮演什么角色YAML 是 openrig 这类方案的“配置骨架”。为什么不用 JSON因为 JSON 不支持注释写配置的人没法在文件里标注“这一行是干嘛的”。为什么不用 TOMLTOML 在嵌套结构上不如 YAML 直观。YAML 用缩进表达层级人类读起来接近自然语言特别适合写“模型列表”“工具参数”“环境变量”这种结构化配置。但 YAML 也是新手最容易翻车的地方。它的缩进必须用空格不能用 Tab冒号后面必须跟一个空格列表项的短横线后面也要有空格。我见过太多人因为一个 Tab 键排查了半小时。热搜里“yolov10 yaml文件怎么创建”“rstudio的yaml在哪里”这类问题本质上都是同一个困惑YAML 文件该放哪、怎么写才不报错。在 openrig 的语境下YAML 通常用来定义这几类东西模型提供方provider的地址和密钥、每个工具Claude Code / Codex用哪个模型、以及一些运行时参数超时时间、重试次数。一个典型的配置片段长这样providers: - name: local-lmstudio base_url: http://localhost:1234/v1 api_key: not-needed models: - qwen2.5-coder - deepseek-coder tools: claude-code: provider: local-lmstudio model: qwen2.5-coder codex: provider: local-lmstudio model: deepseek-coder这段配置的意思是我本地跑了一个 LM Studio它暴露了 OpenAI 兼容的接口地址是localhost:1234。然后我让 Claude Code 和 Codex 都走这个本地模型。注意api_key那行本地模型通常不校验密钥但很多客户端要求这个字段不能为空所以随便填一个占位符就行。2.3 openrig 想避免的三个坑我把 openrig 的设计目标归纳成三条这也是它区别于“手动一个个装”的地方。第一避免环境漂移。你今天装好的 Node 版本、npm 全局包、配置文件过一个月换台机器就全乱了。openrig 通过把配置和依赖声明集中管理让“换机器”变成“拉代码 跑一条安装命令”。第二避免模型接入的重复劳动。Claude Code 和 Codex 各自有自己的配置方式一个用环境变量一个用配置文件。openrig 试图用统一的 YAML 描述模型来源再由它分发到各个工具。这样你换模型时只改一处。第三避免“组织策略”类报错把人卡死。热搜里 “your organization has disabled claude subscription access for claude code” 和 “codex无法加载组织设置” 都是账号层面的限制。openrig 的思路是让你能方便地切换到第三方 API 或本地模型绕开对单一账号体系的依赖。这一点对国内用户尤其重要因为很多官方订阅在支付和网络层面都有门槛。3. 核心细节解析Node.js、YAML、模型接入的实操要点3.1 Node.js 安装LTS、镜像源与版本锁定安装 Node.js 这件事说简单也简单说坑也多。我按操作系统分开讲。Windows 用户直接去 Node.js 官网下载 LTS 的安装包。安装过程中有一个选项叫“Automatically install the necessary tools”如果你不打算编译原生模块可以不勾省得它去装一堆 Visual Studio 构建工具。装完之后打开 PowerShell 或 CMD输入node -v和npm -v验证。如果提示“不是内部或外部命令”说明 PATH 没配好重新装一遍并确保勾选 Add to PATH。macOS 用户我强烈建议用 Homebrew 或者 nvm。Homebrew 的brew install node装的是最新稳定版但不一定是 LTS。nvm 更灵活# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.zshrc # 或 ~/.bashrc # 安装 LTS nvm install --lts nvm use --ltsLinux 用户尤其是 Ubuntu系统自带的 apt 源里的 Node 版本往往很旧。不要用apt install nodejs用 NodeSource 的源或者 nvm。热搜里“ubuntu配置claude code”“ubuntu 安装claude code”这类需求第一步就是把 Node 搞对。关于镜像源如果你在国内npm 默认源下载速度可能很慢。可以临时或永久切换到国内镜像# 查看当前源 npm config get registry # 切换到国内镜像 npm config set registry https://registry.npmmirror.com注意切换镜像源只影响包下载速度不影响工具功能。但有些企业内网会屏蔽外部源这时候你需要问清楚内网有没有私有 npm 仓库。版本锁定这块openrig 这类方案通常会在项目里放一个.nvmrc文件内容就一行版本号比如20.11.0。这样团队成员只要nvm use就能自动切到正确版本。这个细节很小但能省掉大量“为什么你那边能跑我这边不行”的扯皮。3.2 YAML 配置从“能跑”到“好维护”写 YAML 配置新手最容易犯的错我列一下你对照检查用了 Tab 缩进。YAML 只认空格通常 2 个空格一级。冒号后面没加空格。name:value是错的必须name: value。列表项短横线后没空格。-item是错的必须- item。字符串里有特殊字符没加引号。比如api_key: abc:def会因为多出来的冒号被解析错应该写成api_key: abc:def。布尔值歧义。yes、no、on、off在 YAML 里会被解析成布尔值如果你想要字符串得加引号。我自己的习惯是写完 YAML 先用一个在线校验器或者python -c import yaml; yaml.safe_load(open(config.yaml))过一遍确认语法没问题再拿去用。这个习惯帮我省了无数次“配置看起来没问题但工具就是报错”的时间。关于配置文件放哪不同工具不一样。Claude Code 通常读用户主目录下的配置Codex 可能读项目目录下的配置。openrig 的价值之一就是它帮你把“哪个文件放哪”这件事标准化了。如果你是自己手动配记住一个原则全局配置放主目录项目级配置放项目根目录项目级覆盖全局。3.3 模型接入本地模型与第三方 API 两条路模型接入是 openrig 最核心的功能。我分两条路讲。第一条路是本地模型。热搜里“claude code 调用lmstudio的本地模型”就是这条路。LM Studio 是一个可以在本地跑大模型的桌面应用它启动后会暴露一个 OpenAI 兼容的接口默认地址是http://localhost:1234/v1。你要做的是在 openrig 的 YAML 里把这个地址配上然后让 Claude Code 或 Codex 指向它。本地模型的好处是数据不出本机、不花钱、不怕断网。坏处是对硬件有要求而且小模型的能力跟云端大模型差距明显。我的建议是如果你只是想让 AI 帮你写写脚本、改改配置7B 到 14B 的代码模型够用如果你要它理解大型项目还是得用云端模型。第二条路是第三方 API。热搜里“codex接入deepseek”“使用cc switch 接入 deepseek v4, qwen, glm等模型”都是这个方向。国内有不少模型提供方提供 OpenAI 兼容的接口你只要拿到 base_url 和 api_key就能接进来。配置方式跟本地模型几乎一样只是地址换成对方的域名。这里有个关键点不是所有模型都支持所有工具需要的接口格式。比如 Codex 可能依赖/responses这个端点而某些第三方 API 只实现了/chat/completions。热搜里 “cc switch local proxy failed while handling codex endpoint /responses” 这个报错本质就是代理层没能正确转发或转换这个端点。遇到这种情况你要么换一个兼容性更好的提供方要么在中间加一层转换代理。提示接入第三方 API 时先在终端用 curl 测一下端点通不通再去配工具。这样能把“网络问题”和“配置问题”分开排查。curl http://localhost:1234/v1/models # 如果返回模型列表说明本地服务正常4. 完整实操流程从零搭一套能跑的 openrig 环境4.1 环境准备清单与安装顺序我把整个流程拆成六步顺序很重要因为后面的步骤依赖前面的结果。安装 Node.js LTS用 nvm 或官网安装包。配置 npm 镜像源国内用户。安装 Claude Code 和 Codex 的 CLI 包。准备模型来源本地 LM Studio 或第三方 API。编写 openrig 的 YAML 配置。验证每个工具能否正常调用模型。第一步和第二步前面讲过了。第三步安装命令通常是全局安装npm install -g anthropic-ai/claude-code npm install -g openai/codex包名可能会变以官方文档为准。装完之后用claude --version和codex --version验证。如果提示命令找不到检查 npm 全局 bin 目录有没有在 PATH 里。npm config get prefix可以看到全局安装位置。第四步如果你用 LM Studio打开它下载一个代码模型比如 Qwen2.5-Coder 7B然后在“Local Server”标签页启动服务。确认端口是 1234并且勾选了“OpenAI Compatible API”。如果你用第三方 API去对方控制台拿到 base_url 和 key。4.2 YAML 配置文件的完整写法与参数说明下面是我自己用的一套配置模板你可以直接抄改掉地址和模型名就行。version: 1 providers: - name: lmstudio type: openai-compatible base_url: http://localhost:1234/v1 api_key: lm-studio timeout: 120 models: - qwen2.5-coder-7b-instruct - deepseek-coder-v2 - name: remote-api type: openai-compatible base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} timeout: 60 models: - deepseek-chat - qwen-max tools: claude-code: provider: lmstudio model: qwen2.5-coder-7b-instruct max_tokens: 4096 temperature: 0.2 codex: provider: remote-api model: deepseek-chat max_tokens: 8192 temperature: 0.1几个参数我解释一下。timeout是请求超时时间本地模型推理慢设大一点120 秒比较稳妥。temperature控制输出的随机性写代码场景建议 0.1 到 0.3太高了它会瞎编。max_tokens是单次回复的最大长度设太小会被截断设太大浪费资源。api_key那里用了${REMOTE_API_KEY}这是从环境变量读取的写法避免把密钥硬编码进文件。这个习惯很重要尤其是你要把配置提交到 Git 仓库的时候。注意如果你的 YAML 里要写 Windows 路径反斜杠要转义或者用正斜杠。比如C:\Users\me在 YAML 里可能出问题写成C:/Users/me更安全。4.3 验证与联调怎么确认真的通了配置写完别急着在项目里用。先做最小验证。对 Claude Code你可以直接问它一个简单问题看它有没有走你配的模型。如果它回复的内容风格跟你选的模型一致说明通了。如果报错看错误信息里的端点地址是不是你配的那个。对 Codex类似。如果报 “model is not supported” 这类错说明你配的模型名跟提供方实际支持的模型名对不上。去提供方的模型列表里核对准确名称。我自己的验证顺序是先用 curl 直接打提供方的接口确认网络和密钥没问题再用工具自带的“列出模型”命令确认工具能读到模型列表最后才发一个实际请求。这样分层排查出问题时能快速定位是哪一层的问题。# 第一步curl 测提供方 curl -s http://localhost:1234/v1/models | head -c 500 # 第二步工具侧验证以 Claude Code 为例具体命令以官方为准 claude --list-models4.4 把配置纳入版本管理openrig 的“rig”感很大程度来自它可版本管理。我建议你把 YAML 配置、.nvmrc、以及一个简短的 README 放进 Git 仓库。README 里写清楚需要哪个 Node 版本、怎么装依赖、怎么启动本地模型、怎么设置环境变量。这样别人 clone 下来照着 README 走一遍就能跑起来。密钥不要进仓库。用.env文件或者系统环境变量然后在.gitignore里把.env排除掉。如果团队协作可以用一个.env.example文件列出需要哪些变量但不填真实值。5. 常见问题与排查技巧实录5.1 安装类报错速查报错关键词可能原因解决方向node.js v24.21.0 is not yet released工具声明了不存在的 Node 版本换 LTS 版本或用 nvm 切到可用版本command not found: claudenpm 全局 bin 不在 PATH检查npm config get prefix把 bin 目录加入 PATHEACCES permission denied全局安装权限不足不要用 sudo改用 nvm 管理 Nodenpm install 卡住不动默认源太慢切换国内镜像源安装类问题九成出在 Node 版本和 PATH 上。我的建议是遇到安装报错先node -v和npm -v看版本再which node看路径基本能定位。5.2 模型接入类报错速查报错关键词可能原因解决方向connection refused本地模型服务没启动检查 LM Studio 是否在运行端口是否对401 unauthorizedAPI key 错误或缺失核对 key确认环境变量已加载model is not supported模型名写错用提供方的模型列表核对准确名称/responses endpoint failed提供方不支持该端点换提供方或加转换代理organization has disabled access账号策略限制切换到第三方 API 或本地模型“organization has disabled claude subscription access” 这个报错我单独说一下。它通常出现在你用某个组织账号登录但该组织关闭了 Claude Code 的访问权限。解决办法有两个换一个个人账号或者干脆走第三方 API / 本地模型绕开账号体系。这也是 openrig 这类方案存在的意义之一——它让你对单一账号的依赖降到最低。5.3 我踩过的三个坑第一个坑YAML 里用了 Tab。那次我排查了四十分钟最后用cat -A config.yaml才看到^I字符。现在我写 YAML 第一件事就是确认编辑器把 Tab 转成了空格。第二个坑本地模型端口冲突。LM Studio 默认 1234但我机器上另一个服务占了这个端口导致 Claude Code 连上去后返回的是另一个服务的响应。排查方法是lsof -i :1234看谁在占用。第三个坑环境变量没生效。我在.env里写了 key但工具启动时没加载这个文件。后来改成在 shell 配置里export或者用工具支持的--env-file参数才解决。环境变量的加载顺序是个容易被忽略的细节。5.4 性能与体验优化的小技巧本地模型推理慢这是硬件决定的但你可以通过几个设置改善体验。一是把max_tokens调小让它别生成太长二是用更小的量化模型比如 4-bit 量化版速度会快不少三是把temperature调低减少它“思考”的时间。如果你同时用 Claude Code 和 Codex建议给它们配不同的模型。比如 Claude Code 配一个擅长对话和解释的模型Codex 配一个擅长补全代码的模型。这样各取所长体验更好。还有一点日志要开。很多工具支持--verbose或DEBUG*环境变量。出问题时打开日志能看到它实际请求的地址和参数比猜快得多。6. 关于 openrig 后续可以怎么扩展这套东西搭起来之后能扩展的方向不少。我列几个我自己在用的。一是加一个健康检查脚本。每次开工前跑一下自动检测 Node 版本、模型服务是否在线、配置文件语法是否正确。有问题提前发现别等到写代码写到一半才发现模型连不上。二是把配置模板化。不同项目用不同模型你可以准备几套 YAML用符号链接或者环境变量切换。比如config.local.yaml和config.remote.yaml需要哪个就软链到config.yaml。三是接入更多工具。openrig 的思路不局限于 Claude Code 和 Codex任何读配置、走 OpenAI 兼容接口的 CLI 工具都能纳进来。你只要在 YAML 里加一段tools配置就行。四是做团队分发。把仓库做成模板新成员 clone 下来跑一个make setup或者npm run setup自动装依赖、拉模型、生成配置。这一步做完团队里“环境不一致”的问题基本就消失了。我个人在实际操作中的体会是openrig 这类方案最大的价值不在于它省了多少安装时间而在于它把“环境”这件事从“每个人各自的手艺”变成了“可复制、可审查、可交接的工程资产”。你踩过的坑写进配置和 README 里下一个人就不用再踩。这才是它作为“rig”的真正意义——一个稳固的、开放的工作台而不是一堆散落的命令。