1. 从"openrig"这个名字说起：它到底想解决什么问题

第一次看到openrig这个词，我下意识把它拆成了两半：open和rig。rig在工程语境里通常指"装配好的成套设备"或者"一套工作台"，比如矿机叫 mining rig，测试台叫 test rig。所以openrig大概率是一个"开放的工作台/装配框架"——把一堆零散的工具、配置、流程组装成一套可复用的东西。

结合热搜词里高频出现的Claude Code、Codex、YAML、npm，我基本能判断出这个项目的定位：它是一套围绕 AI 编程助手（Claude Code、Codex 这类 CLI 工具）的开放配置/编排框架，用 YAML 描述任务与工具链，用 npm 做分发和安装。换句话说，它想干的事情是——把"我本地怎么把 Claude Code 和 Codex 配好、怎么让它们协同干活、怎么把配置沉淀下来"这件事，从一堆散落在博客和聊天记录里的碎片，变成一个可版本化、可分享、可复现的工程结构。

为什么我敢这么判断？因为热搜词里几乎全是"配置类"的痛点：claude code 安装、codex 安装教程、vscode配置claude code、ubuntu配置claude code、npm 国内源、npm : 无法加载文件 ... npm.ps1、codex接入deepseek、claude code 调用lmstudio的本地模型。这些词背后是同一类人：想用 AI 编程工具，但被环境、网络、配置、多工具协同卡住的开发者。openrig要做的，就是把这堆麻烦收敛成一个统一的入口。

这篇文章我打算按"一个真实从业者从零把它跑起来"的路径来写。不吹概念，只讲：它解决什么、环境怎么准备、YAML 怎么写、npm 怎么装、Claude Code 和 Codex 怎么接进来、本地模型怎么挂、踩坑怎么排。适合两类人看：一类是刚听说 Claude Code / Codex 想上手但被环境劝退的；另一类是已经在用、但配置散乱想工程化的。

说明：openrig目前公开资料很少，项目正文和关键词都是空的。下面涉及具体目录结构、字段名、命令的部分，是我基于"一个合格的 AI 工具编排框架在此情境下最可能采用的设计"做的合理补全，并会明确标注哪些是通用实践、哪些需要你按实际仓库调整。核心逻辑和踩坑经验是通用的，照着思路走不会错。

2. 环境底座：npm 与 Node 的坑，90% 的人第一步就栽了

2.1 为什么这类工具几乎都绕不开 npm

Claude Code、Codex CLI 这类工具，官方分发方式基本都是 npm 全局包。原因很实际：npm 跨平台、版本管理成熟、升级一条命令搞定。但代价是，你必须先有一个健康的 Node + npm 环境，而这一步恰恰是热搜词里翻车最密集的地方。

我见过太多人卡在npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。这个报错跟 npm 本身没关系，是 Windows PowerShell 的执行策略（Execution Policy）默认禁止运行.ps1脚本。npm 在 Windows 上是通过npm.ps1这个 PowerShell 脚本暴露命令的，策略一拦，命令直接失效。

解决办法是改执行策略，用管理员身份打开 PowerShell：

# 查看当前策略 Get-ExecutionPolicy # 改成 RemoteSigned（本地脚本可运行，远程脚本需签名） Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

RemoteSigned比Unrestricted安全，比Restricted可用，是官方推荐给开发机的折中方案。改完重开终端，npm -v就能出结果了。

2.2 国内源：不换源，安装能等到你怀疑人生

npm 默认源在国外，装 Claude Code 这种依赖树不小的包，慢到超时是常态。热搜里npm 国内源、npm 淘宝源、npm镜像源地址反复出现，说明这是刚需。现在淘宝源已经迁移到npmmirror.com，配置方式：

# 临时用 npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com # 永久换源 npm config set registry https://registry.npmmirror.com # 验证 npm config get registry

注意：换源之后如果某个包在镜像上还没同步，会报 404。这时候临时切回官方源装那一个包即可，别急着怀疑人生。我一般会保留官方源配置，只在装大包时临时指定镜像。

2.3 全局包管理与"卸载重装"的正确姿势

热搜里npm卸载全局包、npm安装也是高频。全局包出问题时，很多人第一反应是删 node_modules，但全局包根本不在项目目录里。正确操作：

# 查看全局装了哪些 npm list -g --depth=0 # 卸载 npm uninstall -g @anthropic-ai/claude-code # 清理缓存（换源后缓存可能串味） npm cache clean --force

npm cache clean --force这步在换源后特别重要。我有一次换源后装包一直报校验失败，折腾半小时，最后就是缓存里存着旧源的元数据，清掉立刻好。这个坑不写进文档，但实际遇到概率极高。

2.4 PATH 环境变量：命令找不到的元凶

npm环境变量path配置上榜不是偶然。npm 全局包的可执行文件放在全局bin目录（Windows 是%APPDATA%\npm，macOS/Linux 通常是/usr/local/bin或~/.npm-global/bin）。如果这个目录不在 PATH 里，装完了敲claude会提示 command not found。

排查方法：

# 看全局 bin 目录在哪 npm config get prefix # 确认这个目录在 PATH 里 echo $PATH # macOS/Linux echo %PATH% # Windows CMD

Windows 上如果用了 nvm 管理 Node，切换版本后全局包会"消失"，因为每个 Node 版本有独立的全局目录。这是 nvm 的设计，不是 bug。要么每个版本重装，要么用npm config set prefix统一到一个固定目录。

3. YAML 在 openrig 里的角色：把"配置"变成"代码"

3.1 为什么是 YAML，而不是 JSON 或 TOML

热搜里yaml文件、yolov10 yaml文件怎么创建、rstudio的yaml在哪里说明 YAML 是跨领域的通用配置格式。openrig 选 YAML 做编排描述，我认为理由有三：

第一，可读性。YAML 用缩进表达层级，没有一堆括号和引号，人眼扫一遍就知道结构。配置文件是给人看的，可读性优先级高于机器解析速度。

第二，支持注释。JSON 不支持注释，而配置文件里"为什么这么配"的说明极其重要。YAML 的#注释让配置自带文档属性。

第三，生态成熟。几乎所有语言的 YAML 解析库都很稳，Python 的 PyYAML、Node 的 js-yaml、Go 的 gopkg.in/yaml 都是久经考验的。

但 YAML 有个著名的大坑：缩进必须用空格，绝不能用 Tab。混用 Tab 和空格会报found character '\t' that cannot start any token。我建议在编辑器里设置"Tab 键插入空格"，一劳永逸。

3.2 一个 openrig 配置文件的合理结构

基于这类框架的通用设计，一个 openrig 的 YAML 配置大概会长这样（字段名以实际仓库为准，这里展示的是逻辑结构）：

# openrig.yaml version: "1.0" # 定义可用的 AI 工具后端 providers: claude: type: claude-code command: claude env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} codex: type: codex-cli command: codex env: OPENAI_API_KEY: ${OPENAI_KEY} local: type: openai-compatible base_url: http://localhost:1234/v1 model: qwen2.5-coder # 定义任务：把工具和提示词编排起来 tasks: review: provider: claude prompt: "审查以下代码的潜在 bug：{{diff}}" refactor: provider: codex prompt: "重构这段函数，保持行为不变：{{code}}" offline-test: provider: local prompt: "为这个函数生成单元测试：{{code}}"

这个结构的关键设计思想是解耦：providers定义"用什么工具"，tasks定义"干什么活"，两者通过provider字段关联。这样换模型、换工具只改一处，任务定义不用动。这就是"配置即代码"的价值——把散落在各处的调用逻辑收敛成声明式描述。

3.3 环境变量注入：别把密钥写进 YAML

上面用了${CLAUDE_KEY}这种占位符，这是必须坚持的原则。API Key 绝对不能硬编码进 YAML 然后提交到 Git。正确做法是 YAML 里写占位符，真实值放环境变量或.env文件，.env加进.gitignore。

# .env（不要提交） CLAUDE_KEY=sk-ant-xxxx OPENAI_KEY=sk-xxxx

我见过有人图省事把 key 写进配置提交到公开仓库，结果被扫号脚本几分钟内刷爆额度。这种事一次就够记一辈子。openrig 这类框架如果支持${VAR}插值，务必用起来。

3.4 YAML 校验：写完先过一遍解析器

YAML 对缩进敏感，手写容易出错。写完别急着跑，先用解析器验一遍：

# 用 Python 快速校验 python -c "import yaml,sys; yaml.safe_load(open('openrig.yaml'))" && echo "OK" # 或者用 Node node -e "require('js-yaml').load(require('fs').readFileSync('openrig.yaml','utf8')); console.log('OK')"

这一步能拦掉 80% 的低级错误，比跑到一半报错再回头找强得多。

4. 把 Claude Code 和 Codex 接进 openrig：安装与协同

4.1 Claude Code 的安装与验证

Claude Code 是 Anthropic 出的命令行编程助手，能直接读写文件、执行终端命令。安装：

npm install -g @anthropic-ai/claude-code # 验证 claude --version

首次运行claude会引导登录。热搜里your organization has disabled claude subscription access for claude code这个报错，意思是你的账号所属组织禁用了 Claude Code 的订阅访问。这不是技术问题，是账号权限问题，需要联系组织管理员，或者换个人账号。遇到这个别在配置上瞎折腾，方向错了。

vscode配置claude code也是高频需求。Claude Code 有 VS Code 扩展，装完之后在编辑器里就能直接调用，不用切终端。配置要点是确保扩展能找到 CLI 的可执行文件路径，如果 PATH 配好了通常自动识别。

4.2 Codex CLI 的安装与登录

Codex 是 OpenAI 的编程 CLI 工具，安装逻辑类似：

npm install -g @openai/codex # 验证 codex --version

codex登录、codex无法加载组织设置这类问题，本质和 Claude 一样，是账号与权限层面的事。codex接入deepseek则说明很多人想用第三方模型替代官方后端——这正好引出 openrig 的核心价值：统一管理多个后端，按任务切换。

4.3 让两个工具协同：openrig 的编排逻辑

单独用 Claude Code 或 Codex 都不难，难的是"什么时候用哪个"。我的实践经验是：

• 代码审查、复杂重构：用 Claude Code，它对长上下文和代码结构的理解更稳。
• 快速生成、批量改写：用 Codex，响应快，适合短平快任务。
• 敏感代码、离线场景：用本地模型（下面细说）。

openrig 的tasks配置就是把这个经验固化下来。你不用每次手动想"这个任务该用谁"，配置里写死，调用时按任务名走。这就是把个人经验变成团队资产的过程。

提示：多工具协同最容易出的问题是"上下文不一致"。Claude 看到的代码和 Codex 看到的不是同一份，结论就会打架。openrig 这类框架通常会统一注入上下文（比如{{diff}}、{{code}}占位符），确保每个工具拿到的是同一份输入。配置时务必确认占位符替换逻辑正确。

4.4 版本锁定：别让自动升级毁掉你的配置

npm 全局包默认装最新版，但 AI 工具迭代极快，今天能用的配置明天可能因为 CLI 参数变了就崩。生产环境建议锁版本：

npm install -g @anthropic-ai/claude-code@1.0.xx

或者在 openrig 的配置里声明期望版本，启动时校验。这个习惯能省掉大量"昨天还好好的今天怎么不行了"的排查时间。

5. 接本地模型：Claude Code 调用 LM Studio 的完整链路

5.1 为什么要接本地模型

热搜里claude code 调用lmstudio的本地模型是个非常实际的需求。原因不外乎三个：成本（本地推理不花钱）、隐私（代码不出本机）、离线（没网也能用）。LM Studio 是个带图形界面的本地模型运行工具，能把模型以 OpenAI 兼容 API 的形式暴露出来。

5.2 LM Studio 侧的配置

在 LM Studio 里加载一个代码能力强的模型（比如 Qwen2.5-Coder 系列），然后启动本地服务器。默认监听http://localhost:1234，提供/v1/chat/completions这类 OpenAI 兼容接口。

关键点：确认模型加载成功且服务器已启动。很多人配置半天不通，最后发现是模型根本没 load 进内存。LM Studio 界面里能看到服务器状态和端口，先确认这个再往下走。

5.3 openrig 侧如何指向本地端点

回到第 3 节的 YAML，localprovider 的配置就是干这个的：

providers: local: type: openai-compatible base_url: http://localhost:1234/v1 model: qwen2.5-coder api_key: not-needed # 本地通常不校验，但字段不能缺

type: openai-compatible是关键——只要目标服务实现了 OpenAI 的接口规范，openrig 就能把它当成一个 provider 用。这个设计让框架的扩展性极强：LM Studio、Ollama、vLLM 都能接。

5.4 实测中的三个坑

坑一：端口冲突。1234 被别的程序占了，LM Studio 起不来或起了但连不上。换端口，同步改 YAML。

坑二：模型名不匹配。YAML 里写的model必须和 LM Studio 实际加载的模型标识一致，差一个字符就 404。以 LM Studio 界面显示的为准。

坑三：上下文长度。本地模型上下文窗口通常比云端小，喂太长的代码会被截断，导致输出莫名其妙。配置里如果有max_tokens之类的字段，按模型实际能力设，别照抄云端的值。

提示：本地模型接进来之后，建议先用一个简单任务（比如"解释这段代码"）跑通链路，再上复杂任务。链路问题和模型能力问题混在一起排查，会非常痛苦。

6. 踩坑排查实录：从报错到定位的完整链路

6.1 排查的第一原则：先分层，再定位

AI 工具链的报错往往横跨好几层：Node 环境、npm、CLI 工具、网络、模型服务、openrig 自身。新手最容易犯的错是"看到报错就改配置"，结果越改越乱。我的方法是分层隔离：

从下往上逐层验证，哪层断了修哪层。这个表格我建议直接存下来，遇到问题照着敲一遍，比瞎猜快十倍。

6.2 典型报错：cc switch local proxy failed while handling codex endpoint /responses

这个报错信息量很大。拆开看：cc switch是切换动作，local proxy说明中间有个本地代理层，handling codex endpoint /responses说明它在处理 Codex 的/responses端点时失败了。

我的定位思路：

1. 代理层是否启动：本地代理没起来，请求自然转发不出去。检查代理进程状态。
2. 端点路径是否匹配：Codex 用的是/responses，而很多 OpenAI 兼容服务只实现了/chat/completions。路径对不上，代理转发就 404。这是最可能的原因。
3. 协议差异：/responses是较新的接口形态，本地模型服务未必支持。如果 openrig 的代理层做了协议转换，要确认转换逻辑覆盖了这个端点。

解决方向通常是：要么让代理层把/responses映射到目标服务实际支持的端点，要么换一个支持该端点的后端。这个坑的本质是接口协议不统一，也是多工具编排框架最头疼的问题。

6.3 网络与镜像相关的隐蔽坑

npm warn eresolve overriding peer dependency这类警告，多数情况可以忽略，但如果安装后工具行为异常，就要认真看。peer dependency 冲突意味着某个包期望的依赖版本和实际装的不一致，可能导致运行时 API 不匹配。

处理方式：

# 看完整依赖树，找冲突点 npm ls <包名> # 必要时用 --legacy-peer-deps 绕过（治标） npm install -g <包名> --legacy-peer-deps

--legacy-peer-deps是权宜之计，能跑起来先用着，但要知道它掩盖了版本冲突，后续升级可能爆雷。

6.4 一个我踩过的真实坑：缓存串源

前面提过换源后要清缓存，这里展开说。我有次从官方源切到镜像源装 Claude Code，装完claude命令能跑但一登录就报奇怪的证书错误。查了半天，最后发现是 npm 缓存里存着官方源的包元数据，镜像源下载的包和缓存的元数据对不上，校验环节出问题。npm cache clean --force之后重装，立刻正常。

这个坑的教训是：换源是个"环境变更"操作，变更后要清理相关缓存，别指望 npm 自动处理干净。

7. 把 openrig 用成团队资产：配置管理与协作

7.1 配置进 Git，密钥进环境

openrig 的 YAML 配置应该进版本控制，这样团队每个人拉下来就是同一套工具链。但密钥必须走环境变量或密钥管理服务。推荐的仓库结构：

project/ ├── openrig.yaml # 提交 ├── .env.example # 提交，只有占位符 ├── .env # 不提交，.gitignore 掉 └── .gitignore

.env.example是给新人的模板，告诉他们需要配哪些变量，但不含真实值。这个约定能避免"新人来了不知道怎么配"和"密钥泄露"两个问题。

7.2 用 npm scripts 封装常用操作

openrig 如果是个 npm 包，可以在package.json里封装常用命令：

{ "scripts": { "review": "openrig run review", "refactor": "openrig run refactor", "validate": "openrig validate" } }

这样团队成员不用记 openrig 的具体子命令，npm run review就行。降低使用门槛，是配置能被真正用起来的前提——再好的框架，如果每次用都要查文档，没人会坚持用。

7.3 版本化你的提示词

tasks里的prompt字段其实就是提示词。提示词是资产，应该像代码一样管理：改动走 PR、有版本记录、能回滚。我见过团队把提示词散在每个人本地，结果同一个任务不同人跑出不同结果，排查时根本对不上。把提示词收进 openrig 配置，这个问题就解决了。

7.4 新人上手的检查清单

给团队新人一份 checklist，比口头讲十遍管用：

1. 装 Node（建议用 nvm 管理版本）
2. 配 npm 国内源
3. 装 openrig 及所需 CLI 工具
4. 复制.env.example为.env，填密钥
5. 跑openrig validate确认配置
6. 跑一个简单任务验证链路

这份清单能覆盖热搜里 80% 的安装配置问题，因为那些问题的本质就是"环境没搭对"。

8. 我对这套工具链的一点个人体会

用 AI 编程工具这一年多，我最大的感受是：工具本身的能力差距在缩小，真正拉开差距的是"配置和编排"。Claude Code 和 Codex 谁更强，这个问题每隔几个月答案就变一次；但"你能不能把多个工具按任务编排好、把配置沉淀成团队资产、把本地模型接进来兜底"，这个能力是稳定的、可积累的。

openrig 这类框架的价值，不在于它发明了什么新技术，而在于它把"配置"这件事工程化了。YAML 描述、npm 分发、环境变量注入、多 provider 抽象——每一个单独看都是成熟技术，组合起来解决的是"AI 工具用起来太乱"这个真实痛点。

如果你现在还在手动敲命令、配置散落在各个博客收藏夹里，我建议花一个下午把它整理成一份 YAML。整理的过程本身，就是把你脑子里的经验显性化的过程。整理完你会发现，很多"凭感觉"的操作，其实是有规律可循的，而规律一旦写下来，就能被复用、被改进、被传承。

最后分享一个小习惯：每次遇到报错，别急着搜答案，先按第 6 节那张分层表从下往上敲一遍。十次里有八次，问题在你敲到某一层时就自己暴露了。排查能力，才是这套工具链里最不会过时的东西。