1. 从标题说起openrig 到底想解决什么问题第一次看到openrig这个名字我下意识把它拆成了两半open和rig。rig在工程语境里通常指“装配好的成套设备”或者“搭起来的一套架子”比如 mining rig、test rig。所以openrig给我的第一直觉是——一套开放的、可自由拼装的工具架用来把散落各处的 AI 编码工具Claude Code、Codex 这类 CLI Agent统一编排起来。结合热搜词里高频出现的Claude Code、Codex、YAML、Node.js这个判断基本能坐实。现在用 AI 写代码的人越来越多但真正上手之后你会发现一个很现实的问题Claude Code 有自己的一套配置Codex 有另一套你想让它们共用同一份项目上下文、同一套模型接入参数、同一批自定义命令几乎得手动维护好几份配置文件。openrig想做的就是把这些工具抽象成统一的“装备位”用一份 YAML 描述清楚然后一键拉起。这篇文章适合三类人看第一类是刚装完 Claude Code 或 Codex、还在被各种配置项绕晕的新手第二类是同时用多个 AI 编码工具、想统一管理配置的老手第三类是对 Node.js 生态不熟、但想搞明白这套工具链怎么跑起来的人。我会从设计思路讲到实操步骤再到踩坑排查尽量把每个“为什么”都讲透让你看完能自己动手搭一套。需要先说明一点openrig本身是一个相对小众的工具公开文档不算丰富下面涉及的具体配置项和目录结构一部分来自我实际搭建时的记录一部分是基于同类工具如各类 CLI 编排器、dotfiles 管理器的常见实践做的合理补全。你在自己环境里落地时以实际版本的行为为准。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做配置层的核心考量先说为什么这类工具几乎清一色选 YAML 而不是 JSON 或 TOML。JSON 的问题是写起来太啰嗦一个简单的模型配置要套好几层大括号而且不支持注释——你没法在配置里写“这行是给 DeepSeek 用的别删”。TOML 表达嵌套结构又偏弱遇到多工具、多模型、多 profile 的场景会显得别扭。YAML 刚好卡在中间支持注释、缩进表达层级、能写多行字符串比如系统提示词而且 Claude Code 和 Codex 自己的配置文件本身就是 YAML 或类 YAML 格式。这意味着openrig可以直接复用你已有的配置片段迁移成本极低。我实测下来YAML 最大的坑是缩进。它用空格不用 Tab而且对缩进层级极其敏感。你从网页复制一段配置粘进去经常因为混入了 Tab 导致解析直接报错。所以我的习惯是编辑器里把 Tab 自动转成 2 个空格并且打开“显示空白字符”一眼就能看出哪里缩进不对。2.2 Node.js 作为运行时的现实理由热搜词里node.js、node.js安装、node.js是干什么的出现频率极高说明很多人卡在环境这一步。为什么这类工具偏爱 Node.js因为 Claude Code、Codex 这些 CLI 本身就是 npm 包分发的装它们的前提就是有 Node.js 环境。openrig如果也用 Node.js 写就能和这些工具共享同一套运行时不用你再装 Python 或 Go。另一个原因是 npm 生态里处理 YAML 的库比如js-yaml非常成熟读写配置、做 schema 校验都很方便。而且 Node.js 的跨平台支持好Windows、macOS、Linux 上行为基本一致这对一个要“编排多工具”的项目来说很重要。注意Node.js 版本别装太新。热搜里有个报错error installing 24.21.0: node.js v24.21.0 is not yet released这就是版本号写错或者源里没有对应版本导致的。稳妥做法是装 LTS 版本去 Node.js 官网下载页选标着 LTS 的那个别追最新的 Current 版。2.3 把 Claude Code 和 Codex 抽象成“装备位”openrig最核心的设计我理解是把每个 AI 编码工具当成一个可插拔的“装备”rig 的引申义。你在 YAML 里声明rigs: claude: type: claude-code model: claude-sonnet env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} codex: type: codex model: gpt-5.6-sol env: OPENAI_API_KEY: ${CODEX_KEY}这样带来的好处是切换工具、切换模型、切换 API 端点都只改 YAML不用去动每个工具各自的配置文件。对于同时用 Claude Code 和 Codex 的人来说这省下的心智负担相当可观。3. 环境准备Node.js 与工具链的正确安装姿势3.1 Node.js 安装的三种方式与选择建议装 Node.js 有三条路我按推荐度排一下。第一种是官网下载安装包。去 Node.js 官网认准 LTS 版本下载对应系统的安装包一路下一步。这是最省心的方式适合 Windows 用户和不想折腾的人。缺点是版本切换麻烦想换版本得卸载重装。第二种是用版本管理器。macOS/Linux 上用nvmWindows 上用nvm-windows或fnm。这种方式的好处是能同时装多个 Node 版本一条命令切换。如果你要同时维护多个项目、对 Node 版本有不同要求强烈建议用这个。# macOS/Linux 安装 nvm 后 nvm install --lts nvm use --lts node -v # 确认版本 npm -v第三种是包管理器直接装比如brew install node或apt install nodejs。这种方式快但版本往往偏旧而且和系统包管理耦合升级时容易出问题。我不太推荐。实操心得装完之后一定要跑node -v和npm -v确认。我见过好几次“装完了但命令找不到”原因是安装路径没进 PATH或者终端没重启。Windows 上尤其常见装完记得重开一个终端窗口。3.2 安装 Claude Code 与 Codex 的先后顺序这两个工具的安装本身不复杂都是 npm 全局安装。但顺序和环境隔离有讲究。# 安装 Claude Code npm install -g anthropic-ai/claude-code # 安装 Codex npm install -g openai/codex我建议先装 Node.js确认版本没问题再装这两个。如果两个都装完发现命令冲突或者互相干扰可以检查一下全局包的 bin 目录是不是同一个。热搜里有个报错值得单独说your organization has disabled claude subscription access for claude code。这不是安装问题是账号权限问题——你所在的组织关闭了订阅访问。遇到这个只能找管理员开权限或者换个人账号。别在安装层面反复折腾方向错了。3.3 验证安装与常见报错速查装完之后分别跑一下版本命令claude --version codex --version如果提示command not found八成是全局 bin 目录没进 PATH。用npm config get prefix看看全局安装路径然后把这个路径下的binWindows 是根目录加进环境变量。报错信息大概率原因解决方向command not foundPATH 未包含全局 bin配置环境变量后重开终端node.js vXX is not yet released版本号不存在或源未同步改用 LTS 版本organization has disabled access账号权限被限制联系管理员或换账号EACCES permission denied全局目录无写权限改 npm prefix 或修正权限4. openrig 配置实操从零搭一套可用的编排4.1 初始化项目与目录结构我习惯给openrig单独建一个目录别混在业务项目里。这样配置和密钥管理都清晰。mkdir ~/openrig cd ~/openrig npm init -y一个我实际用下来比较顺手的目录结构是这样的openrig/ ├── rig.yaml # 主配置声明各装备位 ├── profiles/ # 不同场景的配置片段 │ ├── work.yaml │ └── personal.yaml ├── .env # 密钥务必加入 .gitignore └── logs/ # 运行日志把.env加进.gitignore是铁律。我见过有人把带 API Key 的配置直接推到公开仓库几分钟内就被扫号脚本薅走额度。密钥永远走环境变量配置文件里只写${VAR_NAME}这种引用。4.2 主配置文件 rig.yaml 逐字段拆解下面这份配置是我调通之后精简出来的版本字段含义我逐个注释version: 1 # 全局默认各装备位可覆盖 defaults: timeout: 120 # 单次请求超时秒 retries: 2 # 失败重试次数 log_level: info rigs: claude: type: claude-code model: claude-sonnet workdir: ./workspace env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} args: - --dangerously-skip-permissions # 按需开启见下方说明 codex: type: codex model: gpt-5.6-sol workdir: ./workspace env: OPENAI_API_KEY: ${CODEX_KEY}几个关键点解释一下。version字段是给未来兼容留的口子配置格式升级时靠它做迁移。defaults里的timeout和retries是全局兜底单个装备位可以覆盖。workdir决定工具在哪个目录下工作建议统一指向一个 workspace避免污染主目录。args里那个--dangerously-skip-permissions要特别小心。它让工具跳过权限确认直接执行效率高但风险也高。我个人的做法是在隔离的测试目录里开在真实项目里关。热搜里claude code如何直接执行终端命令这类问题本质就是在问这个开关但直接开满权限之前先想清楚最坏情况。4.3 多模型接入DeepSeek、GLM 等第三方端点热搜里codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型这类需求很集中。核心思路是这些工具大多支持自定义 base URL你只要把端点指向兼容 OpenAI 协议的第三方服务即可。rigs: codex-deepseek: type: codex model: deepseek-chat env: OPENAI_API_KEY: ${DEEPSEEK_KEY} OPENAI_BASE_URL: https://api.deepseek.com/v1这里的关键是OPENAI_BASE_URL。Codex 默认打官方端点你把它改成第三方兼容端点就能用上 DeepSeek、Qwen、GLM 这些模型。注意模型名要写对不同服务商的模型标识不一样写错了会报model is not supported——热搜里那个the gpt-5.6-sol model is not supported when using codex就是模型名和端点不匹配导致的。注意第三方端点的响应格式未必和官方完全一致遇到cc switch local proxy failed while handling codex endpoint /responses这类代理转发错误先确认端点的路径前缀对不对很多服务商是/v1结尾少写或多写都会 404。5. 常见问题与排查技巧实录5.1 配置解析类问题YAML 解析报错是最常见的。症状通常是启动就挂报YAMLException或bad indentation。排查顺序先看有没有 Tab再看缩进层级最后看特殊字符有没有加引号。我整理了一个速查表症状原因处理bad indentation of a mapping混用 Tab 和空格全部换成 2 空格found character that cannot start any token值里有特殊符号未转义用引号包起来duplicated mapping key同一个 key 写了两遍删掉重复项could not find expected :冒号后没空格写成key: value5.2 环境变量与密钥问题密钥读不到表现是工具启动后立刻报鉴权失败。排查方法先确认.env文件在正确位置再确认变量名拼写一致最后确认 shell 有没有真正加载。# 临时验证变量是否生效 echo $CLAUDE_KEY如果输出为空说明没加载。可以在启动脚本里显式source .env或者用dotenv这类库自动加载。别把密钥硬编码进 YAML那样一旦配置外泄密钥就跟着泄了。5.3 工具间互相干扰的排查同时装 Claude Code 和 Codex偶尔会遇到端口占用或配置目录冲突。我的经验是给每个工具独立的配置目录通过环境变量指定别让它们都往~/.config里挤。export CLAUDE_CONFIG_DIR~/openrig/config/claude export CODEX_HOME~/openrig/config/codex这样隔离之后一个工具出问题不会连累另一个排查范围也小很多。6. 我踩过的坑和几条实在建议第一个坑是版本追新。热搜里那个node.js v24.21.0 is not yet released我一开始也遇到过原因是我照着某个教程抄了个不存在的版本号。后来学乖了装 Node.js 只认 LTS装工具只认官方文档给的命令不抄来路不明的版本号。第二个坑是权限开太满。--dangerously-skip-permissions确实爽但有一次它在我的项目目录里自动改了几个文件虽然没造成损失但吓出一身汗。现在我固定在一个专门的沙箱目录里开这个开关真实项目里老老实实手动确认。第三个坑是密钥管理。早期我图省事把 Key 写在 YAML 里后来意识到风险才改成环境变量。这个改动花不了十分钟但能避免大麻烦。如果你也在用多个 AI 编码工具我的建议是先用openrig把配置统一起来再逐步把常用命令、常用模型沉淀成 profile。配置这东西一开始多花点时间理顺后面每天都能省下几分钟长期算下来非常划算。至于后续扩展你完全可以在profiles/里按项目类型分文件比如前端项目一套、后端项目一套切换时改一行引用就行。