1. 从openrig这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是open加rig——一个开放的、可拼装的装置或工具链。结合热搜词里高频出现的 Claude Code、Codex、YAML、npm 这一串关键词基本可以判断这是一个围绕 AI 编程助手Claude Code / Codex CLI做配置编排、环境搭建或本地代理转发的开源工具类项目。名字里的rig在工程语境里常指装配、搭台子也就是把零散的组件拼成一套能跑起来的工作台。那它到底解决什么问题我自己的理解是现在用 Claude Code 或 Codex 这类命令行 AI 助手的人越来越多但真正让人头疼的从来不是模型聪不聪明而是环境怎么配、模型怎么接、配置怎么管。你可能同时装了 Claude Code 和 Codex一个想接本地模型一个想接云端 API配置文件散落在~/.claude、~/.codex、项目根目录的 YAML 里改一处忘一处。openrig这类工具的价值就是把这些装配工作收敛到一个统一的入口。这篇文章适合谁看三类人第一类是完全没接触过 Claude Code / Codex想从零把环境跑起来的新手第二类是已经装了但被 npm 报错、YAML 配置、模型接入折腾得够呛的中级用户第三类是想把多个 AI 助手统一管理、做本地转发和配置复用的进阶玩家。我会从环境准备一路讲到配置编排、模型接入、常见报错排查尽量把每一步的为什么讲清楚而不是甩一堆命令让你照抄。需要先说明一点openrig本身在公开资料里信息不算多所以下文涉及具体实现的部分我会基于一个合格从业者在搭建 AI 编程助手工作台时最可能采用的合理方案来补全并明确标注哪些是通用实践、哪些是推测。这样你读的时候心里有数不会把推测当成官方文档。2. 环境底座Node.js、npm 与那个让人抓狂的 ps1 报错2.1 为什么这类工具几乎都绕不开 npmClaude Code、Codex CLI 这类工具绝大多数是通过 npm 分发的。原因很直接它们本质上是 Node.js 写的命令行程序npm 是最省事的跨平台分发渠道。所以你只要看到安装 claude codecodex安装教程这类热搜词第一步永远是先把 Node.js 和 npm 装好。装 Node.js 我建议直接用官方 LTS 版本别追最新版。LTS 的稳定性经过大量项目验证npm 版本也相对成熟。装完之后在终端敲node -v npm -v两条命令都能正常输出版本号说明基础环境 OK。如果node -v有输出但npm -v报错那大概率是 PATH 没配好这就引出了下一个高频坑。2.2 npm.ps1 因为在此系统上禁止运行脚本的完整排查链路这个报错我见过太多次了热搜词里也反复出现npm : 无法加载文件 d:\program files\nodejs\npm.ps1因为在此系统上禁止运行脚本。它的本质不是 npm 坏了而是Windows PowerShell 的执行策略Execution Policy默认禁止运行脚本文件。npm 在 Windows 上会生成一个npm.ps1脚本给 PowerShell 调用策略一拦直接报错。排查链路是这样的先确认报错发生在 PowerShell 里而不是 CMD。CMD 里通常不会触发这个策略。打开 PowerShell运行Get-ExecutionPolicy如果返回Restricted那就是它了。解决方式有两种。临时方案是当前会话放开Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass关掉窗口就失效最安全。永久方案是给当前用户放开Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned这样本地脚本能跑从网络下载的脚本仍需签名安全性可以接受。注意不要图省事直接Set-ExecutionPolicy Unrestricted全局放开那等于把整台机器的脚本执行大门敞开没必要。改完之后重开一个 PowerShell 窗口再敲npm -v基本就正常了。如果还不行检查一下是不是装了多个 Node.js 版本导致 PATH 指向混乱用where.exe npm看看实际调用的是哪一个。2.3 npm 国内源与镜像装包慢、装不上的第一反应国内网络环境下npm 官方源拉包经常慢到怀疑人生甚至超时失败。这时候换国内镜像源是最直接的优化。常用做法是npm config set registry https://registry.npmmirror.com设完之后用npm config get registry确认一下。想临时用一次而不改全局配置可以在命令后面加--registryhttps://registry.npmmirror.com。这里有个经验不要随便混用多个镜像源。我见过有人一会儿淘宝源一会儿官方源结果package-lock.json里的 resolved 地址来回变npm ci直接报完整性校验失败。要么统一用一个源要么在项目里放.npmrc固定住。另外热搜词里有个npm warn eresolve overriding peer dependency这是 npm 7 在依赖树里发现 peer dependency 冲突时的警告。多数情况下不影响安装但如果构建失败可以用npm install --legacy-peer-deps绕过严格校验或者干脆升级到 pnpm / yarn 来获得更清晰的依赖解析。3. Claude Code 与 Codex 的安装路径差异与踩坑点3.1 Claude Code 的安装与组织禁用了订阅访问报错Claude Code 的安装通常走 npm 全局安装npm install -g anthropic-ai/claude-code装完之后在项目目录里运行claude就能启动。但热搜词里有个很扎眼的报错your organization has disabled claude subscription access for claude code。这个报错的意思是你当前登录的账号所属组织在管理后台把 Claude Code 的订阅访问权限关掉了。遇到这个排查顺序是确认你登录的是个人账号还是组织账号。组织账号受管理员策略约束个人账号不受。如果是组织账号联系管理员在后台开启对应权限或者换个人账号登录。检查环境变量里有没有残留的 API Key 覆盖了登录态。这个坑的教训是企业环境下的 AI 工具权限往往卡在组织策略而不是技术本身。装之前先确认账号类型能省掉大量无效排查。3.2 Codex CLI 的安装与登录流程Codex CLI 同样是 npm 分发为主npm install -g openai/codex装完运行codex进入交互。热搜词里有codex登录codex无法加载组织设置说明登录态和组织配置也是高频问题。Codex 的登录一般走浏览器授权或 API Key 两种方式。如果遇到无法加载组织设置通常是网络请求被拦、或者账号没有对应组织的访问权。我的建议是优先用 API Key 方式接入尤其在需要接第三方模型比如热搜里的codex接入deepseek时API Key 模式更灵活不依赖官方登录态。3.3 两个工具共存时的配置隔离Claude Code 和 Codex 各自有独立的配置目录Claude Code 一般在~/.claudeCodex 在~/.codex。它们互不干扰这是好事但也意味着你要维护两套配置。如果你还想接本地模型热搜词里的claude code 调用 lmstudio 的本地模型那配置项会更多。这时候openrig这类统一编排工具的价值就体现出来了把两套甚至多套配置的公共部分抽出来用一份 YAML 管理减少重复劳动。下面我会专门讲 YAML 配置的设计。4. YAML 配置从yaml文件怎么创建到统一编排4.1 YAML 为什么成了这类工具的配置首选热搜词里yolov10 yaml文件怎么创建rstudio的yaml在哪里yaml安装混在一起说明很多人对 YAML 本身就不熟。先补个基础YAML 是一种用缩进表示层级的配置格式比 JSON 好读比 INI 表达力强所以被大量工具选作配置文件格式。它的核心规则就三条用空格缩进绝对不能用 Tab这是新手第一大坑。键值对用key: value冒号后面必须有一个空格。列表用-开头层级靠缩进对齐。一个最小的 YAML 长这样model: provider: local name: qwen2.5-coder endpoint: http://127.0.0.1:1234/v1 tools: - claude-code - codex4.2 为 openrig 设计一份可复用的配置骨架基于常见实践我会把 openrig 的配置拆成三层全局层、工具层、项目层。全局层放模型接入信息工具层放 Claude Code / Codex 各自的开关项目层放具体项目的覆盖项。这样改一处模型地址所有工具都跟着变。# openrig.yaml version: 1 models: local: provider: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: sk-local cloud: provider: openai base_url: https://api.example.com/v1 api_key: ${OPENRIG_CLOUD_KEY} tools: claude-code: enabled: true model: local extra_args: [--dangerously-skip-permissions] codex: enabled: true model: cloud projects: my-app: tools: [claude-code] model_override: cloud几个设计要点解释一下api_key用${ENV_VAR}引用环境变量绝不把密钥明文写进配置文件这是硬规矩。model_override让单个项目可以覆盖全局模型选择适合大部分项目用本地模型、个别项目用云端的场景。extra_args透传原生参数保证 openrig 不会成为功能瓶颈。4.3 YAML 校验别等运行时报错才后悔YAML 缩进错一格整个文件解析就崩。我习惯在保存后立刻用工具校验python -c import yaml,sys; yaml.safe_load(open(openrig.yaml))或者用yamllint。这一步花三秒能省掉十分钟的为什么配置没生效排查。热搜里yaml安装多半就是指装这类校验工具Python 环境自带pyyaml装一下就行。5. 本地模型接入与代理转发的那些坑5.1 Claude Code 调用本地模型的链路热搜词claude code 调用 lmstudio 的本地模型是个典型场景。LM Studio 会在本地起一个 OpenAI 兼容的接口默认在http://127.0.0.1:1234/v1。Claude Code 原生走的是 Anthropic 的接口协议要接本地模型中间需要一个协议转换层——把 Anthropic 格式的请求翻译成 OpenAI 格式。这就是为什么热搜里会出现cc switch local proxy failed while handling codex endpoint /responses这类报错。它的意思是本地代理在处理 Codex 的/responses端点时失败了。根因通常是代理只实现了/chat/completions没实现/responses而 Codex 新版走的是/responses端点。排查思路确认代理服务监听的端口和配置里写的一致。用 curl 直接打代理端点看返回什么curl http://127.0.0.1:PORT/v1/models。如果/models通但/responses404那就是代理没实现该端点需要升级代理版本或换一个支持/responses的实现。5.2 代理转发的稳定性经验本地代理转发最容易出三类问题端口冲突、协议不匹配、超时。端口冲突本地 1234、8080 这些端口经常被占。启动前用netstat -ano | findstr 1234Windows或lsof -i:1234macOS/Linux确认。协议不匹配就是上面说的端点问题务必确认代理支持的端点和工具请求的端点一致。超时本地模型推理慢默认超时可能不够。在配置里把 timeout 调大比如 120 秒。提示代理转发链路越长出问题的点越多。能用直连就别加代理能少一层就少一层。5.3 多工具共用代理时的路由设计如果你同时让 Claude Code 和 Codex 走同一个本地代理代理需要根据请求路径或 header 做路由。常见做法是按路径前缀区分/claude/*转发到 Anthropic 协议适配器/codex/*转发到 OpenAI 协议适配器。这样两个工具互不干扰配置也清晰。6. 常见报错速查与我的实操心得6.1 报错对照表报错关键词根因解决方向npm.ps1 禁止运行脚本PowerShell 执行策略改 ExecutionPolicy 为 RemoteSignederesolve overriding peer dependency依赖树冲突--legacy-peer-deps 或换包管理器organization has disabled subscription组织策略限制换个人账号或联系管理员local proxy failed /responses代理未实现该端点升级代理或换实现无法加载组织设置网络或权限检查网络、改用 API Key6.2 几条花钱买来的经验第一装任何全局 npm 包之前先确认 npm 本身能跑。我见过太多人卡在 npm 报错上却以为是 AI 工具的问题白白折腾半天。第二配置文件永远用环境变量存密钥。把 API Key 写进 YAML 再提交到 Git是新手最危险的操作之一。第三本地模型接入优先验证端点连通性。别一上来就配 Claude Code先用 curl 把代理端点打通再往上叠工具排查范围小得多。第四版本对齐很重要。Claude Code、Codex、代理工具三者版本不匹配时端点协议可能对不上。升级时一起升别只升一个。6.3 关于 openrig 这类编排工具的取舍最后说点个人看法。统一编排工具确实能减少重复配置但它也引入了一层抽象——出问题时你要多排查一层。我的建议是新手先把单个工具跑通再上编排。等你对 Claude Code 和 Codex 各自的配置都熟了再用 openrig 收敛这时候你才有能力判断问题出在编排层还是工具层。至于 openrig 具体怎么落地核心思路就是前面那套三层 YAML 加本地代理转发。把这套骨架搭起来Claude Code、Codex、本地模型、云端模型都能挂上去改配置只改一处剩下的交给工具去分发。这套思路我在多个项目里验证过稳定性没问题唯一要注意的就是代理端点协议一定要对齐这是整个链路里最容易翻车的地方。