openrig 工作台：Claude Code 与 Codex 的 YAML 配置与 Node.js 环境搭建指南

1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到 openrig 这个项目名我脑子里蹦出来的第一反应是开放的工作台。rig 在英文里除了钻机、索具还有一层很地道的用法——装配、搭台子比如游戏圈常说的 rigging就是给角色搭骨架。把这个词放到当下 AI 编程工具的语境里openrig 的定位其实非常清晰它想做的是一套开放的、可自由拼装的 AI 编码助手工作台把 Claude Code、Codex 这类命令行智能体和 YAML 配置、Node.js 运行时这套基础设施串成一条顺手的流水线。为什么这个方向值得单独拿出来聊因为现在用 Claude Code 和 Codex 的人越来越多但绝大多数人卡在同一个地方装是装上了配置却是一团乱麻。模型端点怎么切、本地模型怎么接、YAML 文件怎么写、Node.js 版本怎么对齐、代理转发失败怎么排查——这些问题散落在各种零散的教程里没人把它们系统性地串起来。openrig 这类项目要处理的恰恰就是这堆胶水层的活儿。我自己的判断是openrig 的核心价值不在于它发明了什么新模型而在于它把配置管理这件事从玄学变成了工程。它面向的人群也很明确一是在本地跑 Claude Code 或 Codex 的开发者二是想接入本地模型比如通过 LM Studio做私有化实验的人三是被 YAML 和 Node.js 版本问题反复折磨、想找一套稳定模板的运维和全栈同学。哪怕你只是刚听说 Claude Code、还没真正跑起来这篇文章里的配置思路和踩坑记录也能帮你少走至少两三个晚上的弯路。需要提前说明的是openrig 目前公开的细节并不算多下面涉及的具体配置、目录结构、参数取值一部分来自项目本身的思路一部分是我基于 Claude Code、Codex 这类工具在真实环境中的常见实践做的合理补全。我会在关键位置标注哪些是通用做法哪些是我的经验值方便你按自己的环境调整。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做配置层而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置载体这个决定背后有很实在的工程考量。Claude Code 和 Codex 这类工具本身就有大量嵌套配置——模型端点、认证方式、工具权限、上下文窗口、MCP 服务列表层级动辄三四层。用 JSON 写这种结构满屏的引号和花括号改一个字段要在括号堆里找半天用 TOML 虽然清爽但表达深层嵌套和数组对象混合结构时又显得别扭。YAML 的优势在于它对人友好。缩进即层级注释可以直接写在字段旁边多行字符串用|或就能优雅处理。对于 openrig 这种需要频繁调整模型端点、切换本地与远程配置的场景YAML 的可读性直接决定了你排查问题的速度。我实测过一个对比同样一份包含 5 个模型端点、3 个 MCP 服务的配置用 JSON 改错一个逗号要花两分钟定位用 YAML 基本一眼就能看出缩进错位。不过 YAML 也有它的坑这也是 openrig 使用者必须提前知道的缩进必须用空格不能用 Tab冒号后面必须跟空格字符串里的特殊字符要加引号。这些规则看着简单但新手十有八九会在第一次写 YAML 时栽跟头。后面我会专门用一节讲 YAML 的常见报错和排查。2.2 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就是典型的版本踩坑——有人照着某个教程去装一个根本不存在的版本号结果自然是失败。openrig 这类项目通常会把 Node.js 版本要求写进配置或文档里。我的经验是优先用 LTS 版本不要盲目追最新。截至我写这篇文章时Node.js 20.x 和 22.x 的 LTS 是主流选择Claude Code 和 Codex 在这两个版本上的兼容性最稳。如果你在 Ubuntu 上用 NodeSource 的源装 20 是最省事的路径如果你在 Windows 上直接去 Node.js 官网下载 LTS 的安装包别去折腾那些来路不明的绿色版。这里有个细节值得展开为什么很多人装完 Node.js 后 Claude Code 还是报错大概率是 PATH 没配好或者系统里存在多个 Node.js 版本互相打架。openrig 的配置思路里通常会建议你用 nvmNode Version Manager来管理版本这样切换项目时不会污染全局环境。nvm 在 Ubuntu 和 macOS 上体验很好Windows 上可以用 nvm-windows虽然功能略弱但够用。2.3 把 Claude Code 和 Codex 统一到一个工作台openrig 最有意思的地方是它试图把 Claude Code 和 Codex 这两个原本独立的工具通过统一的配置层管理起来。这两者的定位其实有差异Claude Code 更偏向对话式编码助手强调在终端里直接执行命令、读写文件Codex 更偏向代码生成与补全在接入不同模型端点时灵活性更高。把它们放在一起管理的好处是你可以用同一套 YAML 配置定义模型端点然后让两个工具共享。比如你在本地用 LM Studio 跑了一个模型配置里写好端点地址和模型名Claude Code 和 Codex 都能指向它。这种一次配置、多处复用的思路正是 openrig 作为工作台的核心价值。但这里也有个现实问题Claude Code 和 Codex 的配置格式并不完全一致openrig 需要在中间做一层适配。我的做法是维护一个主配置 YAML然后用脚本生成各自需要的格式。这样改一处两边同步避免了两份配置各改各的混乱。3. 核心细节拆解YAML 配置、Node.js 环境与模型接入3.1 YAML 配置文件的结构设计一份典型的 openrig 风格配置我建议按下面的结构来组织。这不是官方模板而是我在多个项目里验证过、可读性和可维护性都比较好的方案# openrig 主配置 version: 1.0 runtime: node: 20.18.0 # 锁定 LTS 版本 package_manager: npm # 或 pnpm / yarn models: - name: claude-sonnet provider: anthropic endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY max_tokens: 8192 - name: local-qwen provider: openai-compatible endpoint: http://127.0.0.1:1234/v1 api_key_env: LOCAL_API_KEY max_tokens: 4096 agents: claude_code: enabled: true default_model: claude-sonnet permissions: allow_shell: true allow_file_write: true codex: enabled: true default_model: local-qwen sandbox: workspace-write mcp_servers: - name: filesystem command: npx args: [-y, modelcontextprotocol/server-filesystem, ./workspace]这份配置里有几个设计点值得说明。第一runtime.node锁定具体版本号而不是写latest这是为了避免今天能跑明天崩的惨剧。第二模型端点用api_key_env引用环境变量而不是把密钥写死在文件里这是安全底线YAML 文件很可能被提交到 Git密钥写进去等于公开。第三agents下面分别配置 Claude Code 和 Codex各自指定默认模型和权限这样切换工具时不用重新配。注意YAML 里所有缩进必须用空格建议统一用 2 个空格。用 Tab 缩进会直接报found character \t that cannot start any token这个错误新手极容易遇到。3.2 Node.js 环境准备Ubuntu 和 Windows 两条路径Node.js 的安装方式直接决定了后续工具能不能顺利跑起来。我按操作系统分开讲因为这两条路径的坑完全不一样。Ubuntu 上的安装我推荐用 NodeSource 的源命令如下# 先清理可能存在的旧版本 sudo apt remove nodejs npm -y sudo apt autoremove -y # 添加 NodeSource 源以 20.x 为例 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 验证 node -v # 应输出 v20.x.x npm -v为什么不直接用apt install nodejs因为 Ubuntu 官方源里的 Node.js 版本往往偏旧可能只有 12 或 14跑 Claude Code 会直接报版本不兼容。NodeSource 的源能保证你拿到较新的 LTS。Windows 上的安装最稳的是去 Node.js 官网下载 LTS 的.msi安装包双击一路下一步。安装时注意勾选Add to PATH否则命令行里找不到 node 命令。装完后打开新的 PowerShell 窗口一定要新开旧窗口的环境变量不会刷新运行node -v验证。如果你需要在多个 Node.js 版本间切换Ubuntu 和 macOS 上用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重开终端后 nvm install 20 nvm use 20 nvm alias default 20Windows 上对应的工具是 nvm-windows去它的 GitHub Releases 页面下载安装包即可。装完后用nvm install 20.18.0和nvm use 20.18.0切换。提示如果你遇到error installing 24.21.0: node.js v24.21.0 is not yet released这类报错说明你指定的版本号根本不存在。去 Node.js 官网的 releases 页面确认实际可用的版本号别照抄教程里的数字。3.3 Claude Code 与 Codex 的安装与配置Node.js 环境就绪后Claude Code 和 Codex 的安装本身不复杂难的是配置。Claude Code 的安装官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-code装完后在项目目录里运行claude就能启动。第一次启动会引导你配置 API 密钥或登录方式。如果你用的是第三方 API 或本地模型需要在配置里指定端点。Codex 的安装类似具体包名以官方文档为准。装完后同样需要配置模型端点。这里有个高频问题cc switch local proxy failed while handling codex endpoint /responses这类报错通常是因为代理层在转发请求时Codex 期望的/responses端点格式和代理实际提供的不一致。排查思路是先用 curl 直接打你的模型端点确认它到底暴露的是/v1/chat/completions还是/v1/responses然后在配置里对齐。VS Code 里集成 Claude Code需要装对应的扩展然后在设置里指向你的 CLI 路径。如果你在 VS Code 里遇到组织已禁用订阅访问这类提示通常是账号权限或订阅状态的问题和本地配置无关需要从账号侧解决。3.4 接入本地模型以 LM Studio 为例让 Claude Code 调用 LM Studio 的本地模型是很多人玩 openrig 的核心诉求。LM Studio 启动本地服务后默认会在http://127.0.0.1:1234暴露一个 OpenAI 兼容的端点。配置要点有三个第一确认 LM Studio 里已经加载了模型并且启动了本地服务器在 LM Studio 的 Developer 标签页里点 Start Server。第二在 openrig 的 YAML 里把端点写成http://127.0.0.1:1234/v1模型名写 LM Studio 里显示的那个标识符。第三API 密钥随便填一个非空字符串即可本地服务通常不校验但很多客户端要求这个字段不能为空。我实测下来本地模型跑 Claude Code 的体验取决于模型能力。小参数模型7B 以下在复杂任务上容易跑偏建议至少用 14B 以上的模型并且把上下文窗口设小一点避免显存爆掉。4. 实操过程从零搭起一套可用的 openrig 工作流4.1 环境初始化与目录规划动手之前先把目录结构规划好这能省掉后面大量的路径混乱。我的习惯是这样openrig-workspace/ ├── config/ │ ├── openrig.yaml # 主配置 │ ├── claude-code.json # 生成的 Claude Code 配置 │ └── codex.toml # 生成的 Codex 配置 ├── scripts/ │ ├── gen-config.sh # 配置生成脚本 │ └── check-env.sh # 环境检查脚本 ├── workspace/ # 实际干活的代码目录 └── .env # 环境变量密钥加入 .gitignore这个结构的好处是配置和代码分离.env单独存放密钥且不进版本控制。scripts目录放生成脚本主配置改完后跑一下脚本自动生成各工具需要的格式。环境检查脚本check-env.sh我建议至少检查这几项#!/bin/bash echo Node.js: $(node -v 2/dev/null || echo 未安装) echo npm: $(npm -v 2/dev/null || echo 未安装) echo Claude Code: $(claude --version 2/dev/null || echo 未安装) echo Codex: $(codex --version 2/dev/null || echo 未安装) # 检查本地模型端点是否可达 curl -s -o /dev/null -w LM Studio: %{http_code}\n http://127.0.0.1:1234/v1/models每次换机器或排查问题时先跑一遍能快速定位是哪一层出了问题。4.2 配置生成脚本的编写主配置是 YAML但 Claude Code 和 Codex 各自需要的格式不同所以需要一个转换脚本。用 Node.js 写最自然因为环境里本来就有// scripts/gen-config.js const fs require(fs); const yaml require(js-yaml); const main yaml.load(fs.readFileSync(./config/openrig.yaml, utf8)); // 生成 Claude Code 配置 const claudeConfig { model: main.agents.claude_code.default_model, permissions: main.agents.claude_code.permissions, mcpServers: main.mcp_servers.reduce((acc, s) { acc[s.name] { command: s.command, args: s.args }; return acc; }, {}) }; fs.writeFileSync(./config/claude-code.json, JSON.stringify(claudeConfig, null, 2)); // 生成 Codex 配置示例按实际格式调整 const codexConfig model ${main.agents.codex.default_model} sandbox ${main.agents.codex.sandbox} ; fs.writeFileSync(./config/codex.toml, codexConfig); console.log(配置生成完成);跑之前先npm install js-yaml。这个脚本的价值在于你只需要维护一份主配置两边工具的配置自动同步改模型端点时不会漏改。4.3 启动与验证的完整流程配置生成后按下面的顺序验证每一步都确认通过再往下走验证 Node.js 版本node -v输出 20.x 或 22.x。验证工具安装claude --version和codex --version都能输出版本号。验证模型端点用 curl 直接打端点确认返回正常。远程端点检查网络本地端点检查 LM Studio 是否在跑。验证配置加载启动 Claude Code看它是否读取到了正确的模型。可以在对话里问一句你当前用的是什么模型虽然不一定准但能看出配置有没有生效。验证工具调用让 Claude Code 执行一个简单命令比如列出当前目录的文件确认 shell 权限配置正确。这个顺序的逻辑是从底层到上层——运行时、工具、端点、配置、功能逐层验证。任何一层出问题都不会影响你对其他层的判断。我见过太多人一上来就测复杂任务结果报错后不知道是模型问题还是配置问题白白浪费时间。4.4 参数选择与性能调优模型参数这块有几个值直接影响体验我按重要性排一下参数建议值说明max_tokens4096-8192太小会导致回答被截断太大浪费显存temperature0.2-0.5编码任务建议偏低减少随机性context_window按模型能力本地模型别超过显存能承受的范围timeout60-120s本地模型推理慢超时设短了会频繁中断本地模型特别要注意context_window。很多人把上下文设得很大结果模型加载后显存不够推理速度慢到无法忍受。我的经验是先用小上下文跑通再逐步加大找到速度和能力的平衡点。5. 常见问题与排查技巧实录5.1 YAML 报错速查YAML 的报错信息往往很晦涩我整理了一份高频问题对照表报错信息原因解决found character \t that cannot start any token用了 Tab 缩进全部换成空格mapping values are not allowed here冒号后没跟空格key: value而非key:valuedid not find expected key缩进层级不一致检查同级字段缩进是否对齐could not find expected :字符串里有未转义的冒号给字符串加引号duplicate key同一个键写了两次删掉重复项排查 YAML 最有效的办法是用在线校验工具先过一遍或者用python -c import yaml; yaml.safe_load(open(file.yaml))快速验证语法。5.2 模型端点连接失败排查cc switch local proxy failed while handling codex endpoint /responses这类报错排查路径我总结成三步第一步确认端点本身活着。curl http://127.0.0.1:1234/v1/models能返回模型列表说明服务正常。第二步确认路径格式。Codex 可能期望/responses而你的服务只提供/chat/completions这种不匹配需要中间层做转换或者换一个兼容的服务。第三步确认认证头。有些服务要求Authorization: Bearer xxx缺了会返回 401。提示排查网络问题时永远先用 curl 手动打一遍确认端点行为再去调工具配置。工具的报错信息经常把底层问题包装得面目全非。5.3 Node.js 版本冲突的处理系统里装了多个 Node.js 版本时node -v显示的和你以为的可能不一致。排查方法which -a node # 列出所有 node 可执行文件 echo $PATH # 看 PATH 顺序 nvm current # 如果用 nvm看当前版本如果发现 PATH 里有个旧版本的 node 排在前面要么调整 PATH 顺序要么用 nvm 统一管理。Windows 上还要注意有些软件会自带 node.exe 并把它加进 PATH这种隐形的版本冲突最难查。5.4 我的独家避坑清单踩了这么多坑有几条经验是文档里不会写的别在配置里写死密钥。用环境变量.env加进.gitignore。我见过有人把 API 密钥提交到公开仓库几小时内就被刷爆额度。本地模型先小后大。先用小模型跑通流程确认配置无误再换大模型。一上来就用大模型出问题时你分不清是配置问题还是模型问题。保留一份最小可用配置。当复杂配置出问题时用最小配置快速验证基础环境是否正常能大幅缩短排查时间。版本号写具体别写 latest。latest今天能用不代表明天能用锁定版本是稳定性的前提。每次改配置前先备份。YAML 改错一个缩进就可能整个文件失效备份能让你随时回滚。6. 这套工作流的延展与个人体会openrig 这套思路搭起来之后其实可以往几个方向继续扩展。一个方向是加一层健康检查定时探测各个模型端点的可用性端点挂了自动切换到备用端点。另一个方向是把配置做成模板库不同项目用不同的模板切换项目时一键加载。还有一个方向是接入更多的 MCP 服务把文件系统、数据库、浏览器这些能力都挂上去让 Claude Code 和 Codex 真正变成一个全能工作台。我自己在实际操作中的体会是这类工具链的稳定性八成取决于配置管理做得好不好而不是模型本身有多强。一个配置清晰、版本锁定、密钥隔离的工作流哪怕用的是中等能力的模型用起来也比配置混乱的顶级模型顺手。反过来配置一团糟的时候再强的模型也会被各种环境问题拖垮。最后再分享一个小技巧把常用的排查命令做成一个 shell 函数或者 alias比如checkall一键跑完 Node.js 版本、工具版本、端点连通性检查。每次环境出问题先跑一遍能省掉大量重复的手动检查。这套东西搭一次后面几个月都省心。