1. 从“openrig”说起一个被低估的本地 AI 编码环境编排思路第一次看到openrig这个词我脑子里蹦出来的不是某个具体软件而是一种“搭台子”的感觉——rig 在英文里本来就有“装配、搭建、成套设备”的意思open 则点明了它的开放属性。把这两个词拼在一起再结合claude code、codex、yaml、node.js这几个热搜词基本能还原出它想解决的问题把 Claude Code、Codex 这类命令行 AI 编码工具和本地模型、第三方 API、YAML 配置、Node.js 运行时这一整套东西用一个开放、可编排的方式串起来让开发者不再被单一工具或单一模型绑死。我自己从 Claude Code 刚开放命令行形态那会儿就开始折腾中间踩过的坑包括但不限于Node.js 版本对不上导致安装直接报错、YAML 缩进写错让整个配置静默失效、Codex 登录后提示组织设置被禁用、本地 LM Studio 的模型接进去之后响应格式对不上。这些问题单看都是小事但堆在一起就非常消耗耐心。openrig这类思路的价值恰恰在于它试图把“环境准备—工具安装—模型接入—配置编排—问题排查”这条链路标准化而不是让每个人从零试错。这篇文章适合三类人看第一类是刚听说 Claude Code 或 Codex、想在自己机器上跑起来但被 Node.js 和 YAML 卡住的新手第二类是已经在用这些工具、想接入本地模型或第三方 API 做混合编排的进阶用户第三类是团队里负责统一开发环境、需要一套可复制配置方案的人。我会把openrig背后的核心逻辑拆开讲把 Node.js、YAML、Claude Code、Codex 这几块的关键细节和实操步骤都补全尽量做到你照着做就能复现。2. 整体设计思路为什么是“编排”而不是“安装”2.1 单一工具的时代已经过去了早两年大家讨论 AI 编码助手基本就是“你用哪个”。现在的问题变成了“你怎么组合”。Claude Code 在终端里的交互体验和代码理解能力有口皆碑Codex 在特定模型和 API 接入上有自己的生态本地 LM Studio 或 Ollama 跑的小模型则在隐私和成本上有优势。一个成熟的开发者工作流往往是白天用云端强模型处理复杂重构晚上用本地模型跑批量的小任务中间还要根据网络情况切换第三方 API。openrig的核心洞察就在这里与其让每个工具各自维护一套配置不如用一个统一的编排层把模型端点、工具行为、环境变量都抽象出来。这个编排层最自然的载体就是 YAML 文件因为它既能表达层级结构又比 JSON 好读好写还方便做版本管理和团队共享。2.2 为什么选 YAML 作为配置载体YAML 在 AI 工具链里出镜率极高不是偶然。Claude Code 的项目级配置、Codex 的模型定义、很多本地推理框架的启动参数都支持 YAML。它的优势在于可读性强缩进表达层级没有大量括号和引号人眼扫一遍就能看懂结构。注释友好可以用#写注释这对记录“为什么这么配”至关重要。多文档支持一个文件里可以用---分隔多个配置块适合把不同模型的配置放在一起。生态成熟Node.js 生态里有js-yaml、yaml等成熟解析库Python 里有 PyYAML几乎不存在解析障碍。但 YAML 也是出了名的“坑王”。缩进用 Tab 还是空格、冒号后面要不要空格、字符串要不要加引号这些细节一旦出错报错信息往往非常隐晦。我在后面会专门用一节讲 YAML 的常见陷阱和排查方法。2.3 Node.js 为什么是绕不开的一环Claude Code 和 Codex 的 CLI 版本绝大多数都是基于 Node.js 分发的。这意味着你的机器上必须有一个可用的 Node.js 运行时而且版本要匹配。热搜词里出现的error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是一个典型问题——你试图安装一个还不存在的版本或者镜像源里没有同步到这个版本。这里的设计思路是把 Node.js 版本管理纳入编排体系而不是依赖系统全局安装。用nvmNode Version Manager或fnm这类工具可以让不同项目使用不同的 Node.js 版本避免“装了一个工具搞崩了另一个工具”的尴尬。openrig如果要做成一个可复制的方案Node.js 版本锁定应该是第一步。2.4 整体架构的抽象描述把上面的思路串起来openrig的架构可以抽象成四层层级职责关键组件运行时层提供 Node.js 环境nvm / fnm / 系统 Node工具层AI 编码 CLI 工具Claude Code、Codex CLI配置层模型端点与行为定义YAML 配置文件接入层本地模型与第三方 APILM Studio、DeepSeek、Qwen、GLM这四层之间通过环境变量和配置文件解耦。工具层不关心模型是本地还是云端只认配置层给的端点配置层不关心运行时怎么来的只要求 Node.js 可用。这种解耦带来的直接好处是换模型不用重装工具换工具不用重写配置。3. 核心细节解析Node.js、YAML 与工具安装的实操要点3.1 Node.js 安装版本选择比安装本身更重要很多人装 Node.js 的习惯是去官网下载一个 LTS 版本双击安装完事。这个做法在单一项目里没问题但当你同时要用 Claude Code、Codex、还有一堆前端工具时版本冲突几乎是必然的。我的建议是直接用版本管理器。在 macOS 和 Linux 上nvm是最成熟的选择在 Windows 上可以用nvm-windows或者fnm。安装命令大致如下# macOS / Linux 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装完成后重新加载 shell 配置 source ~/.bashrc # 或 ~/.zshrc # 安装并使用 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20为什么选 20 而不是最新的 24因为热搜词里那个报错已经说明了问题太新的版本可能还没被镜像源同步或者某些工具的依赖还没适配。LTS 版本经过一段时间验证兼容性最稳。截至我写这篇文章时Node.js 20 和 22 都是 LTSClaude Code 和 Codex 在这两个版本上表现都正常。安装完成后用下面两条命令验证node -v # 应输出 v20.x.x 或 v22.x.x npm -v # 应输出对应的 npm 版本注意如果你在 Windows 上遇到node.js v24.21.0 is not yet released or is not available这类报错先检查你的 nvm 镜像源配置。有些镜像源同步滞后把版本号改成已发布的 LTS 版本通常就能解决。3.2 YAML 文件创建从零写一个能用的配置YAML 文件的创建本身很简单新建一个.yaml或.yml后缀的文件即可。难的是写对内容。下面是一个典型的模型接入配置示例我以接入本地 LM Studio 和第三方 API 为例# openrig-config.yaml # 模型端点定义 models: local-lmstudio: provider: openai-compatible base_url: http://localhost:1234/v1 api_key: lm-studio model_name: local-model max_tokens: 4096 temperature: 0.7 remote-deepseek: provider: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model_name: deepseek-chat max_tokens: 8192 temperature: 0.3 # 工具行为配置 tools: claude-code: default_model: local-lmstudio auto_approve: false max_file_size: 1048576 codex: default_model: remote-deepseek sandbox: true这个配置里有几个关键点值得展开第一api_key用环境变量占位符。直接把密钥写进 YAML 文件是安全大忌尤其是当这个文件要提交到 Git 仓库时。用${DEEPSEEK_API_KEY}这样的占位符实际运行时从环境变量读取既安全又灵活。第二provider字段统一为openai-compatible。现在绝大多数本地推理框架和第三方 API 都兼容 OpenAI 的接口格式统一用这个 provider 可以最大程度复用配置逻辑。第三temperature按用途区分。本地模型跑探索性任务可以高一点第三方 API 做严肃代码生成就调低减少胡编乱造。YAML 的缩进必须用空格绝对不能用 Tab。这是新手最容易犯的错。我建议在编辑器里设置“Tab 自动转换为 2 个空格”VS Code 里搜索editor.insertSpaces和editor.tabSize就能配置。3.3 Claude Code 安装与配置的关键步骤Claude Code 的安装方式随着版本迭代有过变化目前主流的方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在项目目录下运行claude即可启动。首次启动会引导你完成认证。如果你在 VS Code 里使用可以安装 Claude Code 的 VS Code 扩展然后在设置里配置 CLI 路径。热搜词里有一个your organization has disabled claude subscription access for claude code这个报错的含义是你的账号所属组织关闭了 Claude Code 的订阅访问权限。遇到这种情况通常需要联系组织管理员或者改用 API Key 方式认证而不是订阅方式。另一个高频问题是claude code 调用 lmstudio 的本地模型。Claude Code 本身默认走 Anthropic 的端点要让它调用本地模型需要通过环境变量或配置文件把端点指向本地。常见做法是设置ANTHROPIC_BASE_URL环境变量export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio然后在 LM Studio 里启动一个兼容 OpenAI 接口的本地服务端口默认 1234。这样 Claude Code 的请求就会打到本地模型上。实测下来本地小模型在简单代码补全和解释上够用但复杂重构还是建议用云端强模型。3.4 Codex 安装与模型接入的注意事项Codex CLI 的安装同样走 npmnpm install -g openai/codex安装后运行codex启动。Codex 的配置文件和 Claude Code 类似也支持 YAML 或 JSON 格式。热搜词里出现的codex接入deepseek、codex无法加载组织设置、codex登录都是典型场景。codex无法加载组织设置通常和账号权限或网络有关。如果你用的是第三方 API 接入需要在配置里明确指定base_url和api_key绕过默认的组织认证流程。codex接入deepseek的配置思路和上面 Claude Code 接 LM Studio 类似核心是把端点指向 DeepSeek 的 API 地址模型名改成deepseek-chat或deepseek-coder。还有一个热搜词是{detail:the gpt-5.6-sol model is not supported when using codex with a}这个报错说明你配置的模型名不被当前 Codex 版本支持。解决办法是检查模型名拼写或者换一个已支持的模型。模型名这种东西一定要以官方文档为准不要凭记忆写。4. 实操过程从零搭建一套可用的 openrig 环境4.1 环境准备与版本锁定假设你是一台全新的 Ubuntu 机器或者 Windows 上装了 WSL。第一步是装 Node.js 版本管理器。我以 Ubuntu 为例# 更新包列表 sudo apt update # 安装 curl如果还没有 sudo apt install -y curl # 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 加载 nvm export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20验证node -v npm -v如果node -v输出v20.x.x说明运行时层就绪。这一步看起来简单但它是后面所有步骤的基础。我见过太多人跳过版本管理直接用系统自带的 Node.js结果装 Claude Code 时报一堆依赖错误。4.2 安装 Claude Code 与 Codex两个工具可以并行安装互不影响# 安装 Claude Code npm install -g anthropic-ai/claude-code # 安装 Codex CLI npm install -g openai/codex安装完成后分别验证claude --version codex --version如果这两个命令都能输出版本号说明工具层就绪。如果报command not found检查 npm 全局 bin 目录是否在 PATH 里。可以用npm config get prefix查看全局安装路径然后把这个路径下的bin目录加到 PATH。4.3 编写 openrig 配置文件在项目根目录新建openrig.yaml内容参考 3.2 节的示例。这里我再补充一个更完整的版本包含多个模型和工具配置# openrig.yaml version: 1.0 # 全局设置 global: log_level: info timeout: 120 retry: 2 # 模型端点 models: local: provider: openai-compatible base_url: http://localhost:1234/v1 api_key: not-needed model_name: qwen2.5-coder-7b max_tokens: 4096 temperature: 0.7 deepseek: provider: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} model_name: deepseek-chat max_tokens: 8192 temperature: 0.3 glm: provider: openai-compatible base_url: https://open.bigmodel.cn/api/paas/v4 api_key: ${GLM_API_KEY} model_name: glm-4 max_tokens: 8192 temperature: 0.5 # 工具绑定 tools: claude-code: model: local working_dir: . ignore_patterns: - node_modules - .git - dist codex: model: deepseek sandbox: true approval_mode: suggest这个配置的关键设计是模型与工具解耦。models段定义所有可用端点tools段通过model字段引用。想换模型只改tools里的引用名即可不用动模型定义。4.4 环境变量与密钥管理配置文件里用了${DEEPSEEK_API_KEY}和${GLM_API_KEY}两个占位符实际运行时需要设置对应的环境变量。推荐做法是写一个.env文件然后通过dotenv或 shell 的source命令加载# .env 文件内容 export DEEPSEEK_API_KEYyour-deepseek-key export GLM_API_KEYyour-glm-key加载source .env注意.env文件必须加入.gitignore绝对不要提交到版本库。我见过有人把带密钥的.env推到公开仓库结果密钥被扫走账单直接爆掉。4.5 启动与验证配置写好后启动本地模型服务以 LM Studio 为例在界面里加载模型并启动 OpenAI 兼容服务然后运行claude如果 Claude Code 能正常启动并响应说明整条链路通了。再测试 Codexcodex两个工具都能用之后你可以尝试在 Claude Code 里让它执行一个简单任务比如“解释当前目录下的 package.json”观察它是否走的是你配置的模型端点。如果响应速度明显快于云端说明本地模型生效了。5. 常见问题与排查技巧实录5.1 Node.js 相关报错速查报错信息可能原因解决方法node.js v24.21.0 is not yet released版本号不存在或镜像未同步改用 LTS 版本如 20 或 22command not found: nodeNode.js 未安装或 PATH 未配置检查 nvm 是否加载重新 source shell 配置npm install卡住不动镜像源慢或网络问题切换 npm 镜像源或使用--registry参数全局安装后命令找不到npm 全局 bin 不在 PATH把npm config get prefix下的 bin 加入 PATH5.2 YAML 配置不生效的排查思路YAML 最坑的地方是语法错误不一定报错而是静默失效。比如缩进多了一个空格解析器可能把它当成另一个层级的键而不是报错。排查时按这个顺序来用在线 YAML 校验器过一遍把配置粘贴到校验器里看是否有语法错误。检查缩进确认全部用空格没有 Tab。VS Code 里可以开启“显示空白字符”来检查。检查冒号后的空格key: value冒号后必须有一个空格key:value是错的。检查字符串引号包含特殊字符的值要加引号比如base_url: http://localhost:1234/v1。打印解析结果用 Node.js 写个小脚本把 YAML 解析成 JSON 打印出来看结构是否符合预期。// check-yaml.js const fs require(fs); const yaml require(js-yaml); try { const doc yaml.load(fs.readFileSync(openrig.yaml, utf8)); console.log(JSON.stringify(doc, null, 2)); } catch (e) { console.error(YAML 解析失败:, e.message); }运行node check-yaml.js如果输出结构和你预期一致说明 YAML 没问题如果报错错误信息会指出行号按行号去查。5.3 Claude Code 与 Codex 的典型故障Claude Code 提示组织禁用了订阅访问这个报错说明你的认证方式走的是订阅但组织层面关闭了。解决办法有两个一是联系管理员开通二是改用 API Key 认证。设置ANTHROPIC_API_KEY环境变量并在配置里指定使用 API Key 模式。Codex 无法加载组织设置通常和账号状态或网络有关。如果你用的是第三方 API 接入确保配置里的base_url和api_key正确并且模型名是官方支持的。热搜词里那个gpt-5.6-sol不支持的报错就是模型名写错了。本地模型响应格式不对LM Studio 或 Ollama 的 OpenAI 兼容接口有时候在流式响应上和官方有细微差异。如果 Claude Code 或 Codex 报解析错误尝试在配置里关闭流式输出或者换一个兼容性更好的本地推理框架。cc switch local proxy failed while handling codex endpoint /responses这个报错说明本地代理在处理 Codex 的/responses端点时失败了。排查方向是检查代理配置里的端点路径是否正确以及本地服务是否真的在监听对应端口。用curl http://localhost:1234/v1/models测试一下本地服务是否可达。5.4 我踩过的几个坑坑一Node.js 版本混用。我一开始系统里装了一个 Node.js 18后来又用 nvm 装了 20结果claude命令有时候走 18 有时候走 20行为不一致。后来统一用 nvm 管理把系统 Node.js 卸载了问题消失。坑二YAML 里写了中文注释但编码不对。有一次配置文件里写了中文注释保存时用了 GBK 编码解析器直接报错。后来统一用 UTF-8再没出过问题。坑三API Key 泄露。早期图省事把密钥直接写在 YAML 里结果提交到了 Git。虽然及时发现删除了但密钥已经暴露。现在一律用环境变量并且.env文件永远在.gitignore里。坑四本地模型端口冲突。LM Studio 默认用 1234 端口但我机器上另一个服务也占用了 1234导致 Claude Code 连不上。用lsof -i :1234查了一下发现冲突后改端口解决。6. 进阶玩法多模型编排与团队共享配置6.1 按任务类型自动切换模型openrig的配置层如果设计得当可以支持按任务类型自动切换模型。比如简单补全走本地模型复杂重构走云端强模型。实现方式是在配置里定义路由规则routing: rules: - match: explain|comment|docstring model: local - match: refactor|rewrite|optimize model: deepseek - match: .* model: glm这个路由逻辑需要在工具层做适配不是所有 CLI 工具都原生支持。但你可以写一个包装脚本根据任务描述选择不同的环境变量再启动工具。6.2 团队共享配置的最佳实践团队里每个人机器环境不同但配置可以共享。我的做法是把openrig.yaml提交到仓库作为团队标准配置。把.env.example提交到仓库列出所有需要的环境变量名但不含真实值。每个人本地复制.env.example为.env填入自己的密钥。在 README 里写清楚 Node.js 版本要求和安装步骤新人照着做就能跑起来。这样既保证了配置一致性又避免了密钥泄露。6.3 配置版本管理与回滚YAML 配置文件也是代码应该纳入版本管理。每次修改配置都写清楚改了什么、为什么改。如果新配置导致工具行为异常可以快速回滚到上一个版本。我习惯在配置顶部加一个version字段每次大改就递增方便追踪。7. 一些个人体会折腾openrig这套东西最大的收获不是某个具体工具用得多溜而是建立了一种“环境即配置”的思维。以前装工具是装工具配环境是配环境出了问题靠记忆和运气排查。现在把运行时、工具、模型、配置分层管理每一层都有明确的职责和验证方法出问题时能快速定位到是哪一层的问题。Node.js 版本管理是地基YAML 配置是骨架Claude Code 和 Codex 是上层应用本地模型和第三方 API 是可选插件。这个结构一旦搭好后面换工具、换模型、换机器都只是替换其中一层的事不用推倒重来。如果你刚开始折腾我的建议是先把 Node.js 和 YAML 这两块吃透再装 Claude Code 或 Codex。很多人一上来就装工具结果被 Node.js 版本和 YAML 语法卡住误以为是工具本身的问题。实际上工具本身很少出问题出问题的往往是环境和配置。最后分享一个小技巧每次改完 YAML 配置先用node check-yaml.js验证一遍再启动工具。这个习惯帮我省了大量排查时间。配置这东西宁可多花三十秒验证也不要花三十分钟找错。