1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“装配好的整套装置”比如一台矿机、一套测试台、一组调试工具链。把它放到当下 AI 编程助手满天飞的环境里openrig大概率指向的是一类“把散落的 AI 编码工具组装成一套可复用工作台”的东西——而热搜词里同时出现了 Claude Code、Codex、YAML、npm这个判断基本就坐实了。我先把结论摆在前面openrig这类项目真正要解决的不是“再做一个 AI 编程工具”而是把 Claude Code、Codex 这类命令行 AI 助手通过一份 YAML 配置和 npm 的安装分发机制组装成一套可迁移、可版本管理、可团队共享的本地开发装置。换句话说它管的是“装配”和“编排”不是“模型能力”本身。为什么这个定位很重要因为绝大多数人用 Claude Code 或 Codex 的现状是这样的在 A 电脑上装了一遍配了一堆环境变量写了几条自定义命令换到 B 电脑或者想分享给同事就得从头再来一遍中间还会踩到npm.ps1 无法加载、禁止运行脚本、组织已禁用订阅访问这类环境坑。openrig想做的就是把这些零散的配置沉淀成文件让“装好一套 AI 编码环境”变成一条可复现的流水线。这篇文章适合三类人看第一类是想把 Claude Code、Codex 用起来但被环境配置卡住的新手第二类是想把 AI 编码工具纳入团队规范、做统一分发的工程负责人第三类是对 YAML 驱动配置、npm 包分发这套组合拳感兴趣、想自己搭一套类似装置的折腾党。我会从核心概念、YAML 配置设计、npm 安装链路、Claude Code 与 Codex 的接入差异、以及实际踩坑排查几个角度把这件事讲透。需要提前说明的是openrig目前公开信息非常少项目正文和关键词都是空的所以下文里涉及具体实现的部分我会基于“一个合格从业者在做这类工具时最可能采用的合理方案”来补全并明确标注哪些是推断、哪些是通用实践。这样你读的时候心里有数不会把推断当成官方文档。2. openrig 的核心抽象把 AI 编码工具当成可装配的“机架单元”要理解openrig得先接受一个心智模型AI 编码工具不是孤立的软件而是可以像服务器上架一样被“装配”的单元。这个类比不是玩概念它直接决定了配置该怎么写、目录该怎么组织。2.1 为什么是“机架”而不是“配置集合”普通的 dotfiles 仓库也能管配置为什么还要引入rig这个概念区别在于依赖关系和启动顺序。一台机架上的设备有供电、有网络、有信号链路谁先上电、谁依赖谁是有讲究的。AI 编码工具链也一样npm 全局包得先装好Node 环境得先就位YAML 里定义的模型端点得先能连通Claude Code 或 Codex 才能正常发起请求。如果只是把配置文件堆在一起你得到的是一堆“死”的文件而openrig想给的是一套“活”的装配描述——它知道先装什么、后配什么、哪个环节失败了该回滚。这就是rig和普通 config 的本质差别。我在实际搭类似工具链时最深的一点体会是配置的难点从来不是“写什么”而是“顺序”和“依赖”。你把 npm 源配错了后面所有安装都会失败你把 PowerShell 执行策略忘了改npm命令根本跑不起来。openrig的价值就在于把这些顺序固化下来。2.2 YAML 在这里扮演的角色声明式装配清单热搜词里yolov10 yaml文件怎么创建、yaml文件、yaml安装反复出现说明很多人对 YAML 的认知还停留在“某个项目的配置文件”。但在openrig这类工具里YAML 是声明式装配清单——你描述“我要什么”工具负责“怎么做到”。一份典型的装配清单大概长这样以下为基于常见实践的推断示例rig: name: my-ai-coding-rig version: 1.0.0 runtime: node: 18.0.0 packageManager: npm packages: global: - name: anthropic-ai/claude-code version: latest - name: codex-cli version: latest models: - id: local-lmstudio endpoint: http://127.0.0.1:1234/v1 provider: openai-compatible - id: deepseek endpoint: https://api.deepseek.com/v1 provider: openai-compatible shell: windows: executionPolicy: RemoteSigned unix: shell: zsh这份清单里runtime声明了前置条件packages声明了要装什么models声明了模型端点shell声明了平台差异。工具读取这份 YAML就能在任意机器上复现同一套环境。声明式的好处是幂等——你跑一遍和跑十遍结果应该一致不会因为“上次装了一半”而状态混乱。2.3 npm 作为分发底座为什么不是 pip 或 brew热搜词里npm安装、npm卸载全局包、npm环境变量path配置、npm国内镜像源高频出现说明 npm 是这套链路的核心分发工具。为什么选 npm 而不是 pip 或 brew因为 Claude Code 和 Codex 的官方 CLI 大多以 npm 包形式分发这是生态决定的不是偏好问题。npm 作为分发底座有三个实际好处一是跨平台Windows、macOS、Linux 都能跑二是版本管理成熟package.json和 lock 文件能锁死依赖三是国内镜像源切换方便npm config set registry一条命令就能解决下载慢的问题。但它也有坑最大的坑就是 Windows 上的 PowerShell 执行策略——npm : 无法加载文件 ...\npm.ps1因为在此系统上禁止运行脚本这个报错几乎每个 Windows 新手都会撞上一次。3. 环境准备阶段最容易翻车的三个点在真正跑openrig之前环境准备是淘汰率最高的一关。我把这一关拆成三个最容易翻车的点每个点都给出排查链路而不是直接甩答案。3.1 PowerShell 执行策略那个让 npm 直接罢工的开关Windows 上第一次运行npm命令十有八九会遇到这个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这个报错的本质是PowerShell 的执行策略Execution Policy默认是Restricted它不允许运行任何.ps1脚本而 npm 在 Windows 上正是通过npm.ps1这个脚本入口来工作的。很多人第一反应是“重装 Node”其实完全没必要问题不在 Node在 PowerShell 的安全策略。正确的排查链路是这样的先确认当前策略再决定改到什么级别。# 查看当前执行策略 Get-ExecutionPolicy -List # 查看当前用户的策略 Get-ExecutionPolicy -Scope CurrentUser如果CurrentUser这一项是Undefined或Restricted就需要调整。这里有个经验不要直接改成Unrestricted那等于把安全门全拆了。推荐改成RemoteSigned它的含义是“本地脚本随便跑从网上下载的脚本需要签名”。对开发机来说这个级别在安全和便利之间平衡得最好。Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser用-Scope CurrentUser而不是全局是因为这样只影响你自己的账户不需要管理员权限也不会动到系统级设置。改完之后重开一个终端窗口再跑npm -v大概率就正常了。我踩过的坑是改完策略后没重开终端结果还是报错白白怀疑了半天人生。PowerShell 的策略是会话级加载的改完必须新开窗口。3.2 npm 镜像源国内下载慢和 404 的根源npm 国内源、npm镜像源地址、npm 淘宝源这些词能上热搜说明网络问题确实是刚需。默认的 npm 官方源在国内访问经常超时装一个 Claude Code 可能要等十几分钟甚至直接失败。解决办法是切换到国内镜像源。# 查看当前源 npm config get registry # 切换到国内镜像源 npm config set registry https://registry.npmmirror.com # 验证 npm config get registry这里有个细节很多人不知道镜像源不是万能的某些包在镜像上可能滞后或缺失。如果你装某个包时遇到 404先别急着怀疑包名写错试试临时切回官方源npm install package-name --registryhttps://registry.npmjs.org另外npm warn eresolve overriding peer dependency这个警告也经常出现它表示依赖树里有版本冲突npm 自动帮你覆盖了某个 peer dependency。大多数情况下这个警告可以忽略但如果安装后工具跑不起来就要认真看它覆盖了哪个包。我的经验是遇到 peer dependency 警告先记下被覆盖的包名和版本出问题时这是第一排查线索。3.3 Node 版本与 PATH装好了却“找不到命令”npm环境变量path配置这个词说明很多人遇到过“装完 Node命令行却找不到 npm”的情况。这通常是 PATH 没配好。Windows 上 Node 安装器一般会自动配 PATH但如果你用的是解压版或者手动安装就得自己加。排查方法很简单# 看 npm 到底在哪 where npm # 看 node 版本 node -v # 看 npm 版本 npm -v如果where npm找不到就去系统环境变量里检查Path是否包含 Node 的安装目录通常是C:\Program Files\nodejs\。改完 PATH 同样要重开终端。这里有个隐藏坑如果你同时装了多个 Node 版本比如用 nvm 管理PATH 里的顺序决定了用哪个。where npm会列出所有匹配项第一个就是实际生效的。4. Claude Code 与 Codex 的接入差异同一套 rig两种脾气openrig要同时管 Claude Code 和 Codex就得面对一个现实这两个工具虽然都是命令行 AI 编码助手但接入方式和配置逻辑差别不小。热搜词里claude code 调用lmstudio的本地模型、codex接入deepseek、codex登录、claude code windows这些词正好对应了它们各自的接入难点。4.1 Claude Code 的接入逻辑订阅校验与本地模型绕行Claude Code 的官方形态是绑定订阅的所以你会看到your organization has disabled claude subscription access for claude code这类报错——这不是技术故障是账号权限问题。如果你的组织禁用了订阅访问官方通道就走不通。这时候很多人会转向本地模型也就是热搜里的claude code 调用lmstudio的本地模型。思路是让 Claude Code 把请求发到一个 OpenAI 兼容的本地端点而不是官方服务。LM Studio 正好提供这样的端点默认在http://127.0.0.1:1234/v1。配置的核心是设置环境变量把 API base 指向本地# 以类 Unix 环境为例Windows 用 set 或系统环境变量 export ANTHROPIC_BASE_URLhttp://127.0.0.1:1234/v1 export ANTHROPIC_API_KEYlocal-no-key-needed这里的关键认知是Claude Code 走的是 Anthropic 的 API 协议而 LM Studio 默认暴露的是 OpenAI 兼容协议两者并不完全对等。所以能不能直接对接取决于 LM Studio 是否提供了 Anthropic 兼容层或者中间是否需要一层转换。这是实际接入时最容易卡住的地方不要想当然认为“都是 API 就能通”。4.2 Codex 的接入逻辑CLI 优先端点可换Codex 这边热搜词codex cli、codex接入deepseek、codex安装教程、codex官网下载指向的是它的 CLI 形态。Codex CLI 的接入相对灵活它支持配置自定义的模型端点所以接 DeepSeek 这类 OpenAI 兼容服务比较顺。配置思路通常是改一个配置文件可能是~/.codex/config之类指定 base URL 和 API key# 推断示例具体字段以官方为准 model: deepseek-chat provider: base_url: https://api.deepseek.com/v1 api_key: your-key-herecodex登录和codex无法加载组织设置这两个词说明 Codex 也有账号体系登录态和配置加载是两回事。登录成功不代表配置加载成功如果组织设置拉不下来工具可能回退到默认配置表现就是“登录了但行为不对”。排查时要把这两条链路分开看。4.3 用一张表看清两者的差异维度Claude CodeCodex分发方式npm 全局包npm 全局包 / 独立安装包协议倾向Anthropic API 协议OpenAI 兼容协议本地模型接入需协议兼容层较绕直接支持自定义端点较顺常见报错订阅访问被禁用组织设置加载失败配置位置环境变量为主配置文件为主这张表是我根据热搜词和常见实践整理的实际以官方文档为准。但它能帮你快速判断如果你主要想接本地模型Codex 的路径更短如果你已经在用 Claude 生态Claude Code 更顺手但本地化要多绕一步。5. 把 openrig 跑起来一份可复现的装配流程前面讲的是原理和差异这一节讲怎么落地。我按“从零到能跑”的顺序把流程拆成可复现的步骤。再次强调openrig具体命令未知以下流程是基于这类工具通用形态的合理推断你可以把它当成搭同类装置的参考模板。5.1 前置检查三分钟确认环境就绪在装任何东西之前先花三分钟做前置检查能省掉后面半小时的排查。# 1. 确认 Node 和 npm 可用 node -v npm -v # 2. 确认执行策略Windows Get-ExecutionPolicy -Scope CurrentUser # 3. 确认镜像源 npm config get registry # 4. 确认全局包目录在 PATH 里 npm config get prefix第四步很多人忽略。npm config get prefix会告诉你全局包装到哪这个目录必须在 PATH 里否则你npm install -g装完命令行还是找不到。Windows 上默认是%APPDATA%\npmmacOS/Linux 上通常是/usr/local或~/.npm-global。5.2 安装 openrig 本体全局包的正确姿势假设openrig以 npm 包形式分发安装命令大概是npm install -g openrig装完之后验证openrig --version openrig --help如果openrig命令找不到回到 5.1 的第四步检查 PATH。这里有个经验全局包安装失败时先看是不是权限问题。macOS/Linux 上如果 prefix 是/usr/local可能需要sudo但更好的做法是把 prefix 改到用户目录避免污染系统npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH这样以后所有全局包都装在用户目录不需要 sudo也不会和系统包打架。5.3 编写第一份 rig YAML从最小可用开始不要一上来就写几百行配置从最小可用开始。先定义运行时和要装的包rig: name: minimal-rig version: 0.1.0 runtime: node: 18.0.0 packages: global: - anthropic-ai/claude-code - codex-cli然后让openrig读取并执行推断命令openrig apply -f rig.yaml跑通之后再逐步加models、shell这些段。增量式配置的好处是每一步都可验证出问题能立刻定位是哪一段引入的。我见过太多人一次性写一大坨配置结果报错都不知道从哪查。5.4 验证装配结果别只看“没报错”装配完成后验证不能只看命令有没有报错要实际跑一遍工具# 验证 Claude Code claude --version # 验证 Codex codex --version # 验证模型端点连通性以本地 LM Studio 为例 curl http://127.0.0.1:1234/v1/models第三步特别重要。工具装好了不代表模型能连上端点不通的话工具启动正常但一发请求就失败。提前用 curl 测一下端点能把“工具问题”和“网络问题”分开。6. 踩坑实录那些文档里不会写的排查链路这一节是我最想写的部分因为真正的经验都藏在报错里。我把几个高频坑的完整排查链路还原出来你可以照着复现思路。6.1 npm 全局包装了却“命令不存在”的完整排查现象npm install -g openrig显示成功但openrig命令找不到。排查链路npm config get prefix看全局包目录。去那个目录下看openrig的可执行文件在不在Windows 看.cmdUnix 看软链。如果文件在说明是 PATH 问题如果文件不在说明安装其实没成功。PATH 问题就加 PATH安装问题就回看安装日志。这个链路的价值在于先分清是“装没装上”还是“找不找得到”这两类问题的解法完全不同。很多人一上来就重装其实文件早就在那了只是 PATH 没配。6.2 模型端点连不通从 curl 到配置逐层剥离现象Claude Code 或 Codex 启动正常但一发请求就超时或报错。排查链路先用curl直接打端点确认服务本身活着。如果 curl 通说明是工具配置问题检查 base URL 和 API key。如果 curl 不通说明是服务或网络问题检查服务是否启动、端口是否被占。如果服务在本地检查是不是防火墙拦了。这里有个细节本地模型服务的端口经常被其他程序占用。LM Studio 默认 1234如果这个端口被占服务可能起在别的端口而你的配置还指向 1234自然连不通。用netstat或lsof确认端口占用情况。6.3 组织设置加载失败登录态与配置态要分开看现象Codex 提示无法加载组织设置但登录明明成功了。这个坑的本质是登录态和配置态是两条独立链路。登录成功只证明你的身份验证过了不代表组织级配置能拉下来。可能的原因包括网络访问不到配置服务、组织配置本身有问题、本地缓存损坏。排查顺序先清本地缓存重试再确认网络能访问配置服务最后确认组织侧配置是否正常。不要一看到“登录成功”就认为后面都该顺这是两码事。7. 把 rig 用出长期价值版本管理与团队共享装好一套环境只是开始openrig真正的价值在于让这套环境可版本管理、可团队共享。这一点如果做不好它就只是个一次性安装脚本。7.1 把 rig YAML 纳入 Git配置即代码第一件事是把rig.yaml提交到 Git 仓库。这样每次改配置都有记录出问题能回滚新人入职直接 clone 就能复现环境。配置即代码Configuration as Code这个理念在这里体现得淋漓尽致。建议的仓库结构my-rig/ ├── rig.yaml # 主装配清单 ├── rig.lock # 锁定版本如果有 ├── models/ │ └── endpoints.yaml # 模型端点配置 └── README.md # 使用说明rig.lock这类锁文件的作用是锁定依赖的确切版本避免“今天装和明天装结果不一样”。npm 生态里package-lock.json就是这个角色openrig如果有类似机制一定要用起来。7.2 团队共享时的敏感信息处理团队共享配置时API key 这类敏感信息绝对不能进 Git。正确做法是配置里只放占位符真实值通过环境变量注入models: - id: deepseek endpoint: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY}然后在各自的机器上设置环境变量。这样配置可以公开共享密钥各自保管。这是团队协作里最基本的安全习惯但每年还是有无数密钥因为直接写进配置文件被提交到公开仓库。7.3 多环境切换一份 rig多套 profile实际工作中你可能有多个环境公司内网一套、家里一套、演示环境一套。openrig如果支持 profile 机制就能用一份主配置加多个覆盖文件来管理openrig apply -f rig.yaml -f profiles/home.yaml openrig apply -f rig.yaml -f profiles/work.yaml这种“基础配置 环境覆盖”的模式比维护多份完整配置要清爽得多。基础配置管共性覆盖文件管差异改共性只改一处不会漏。8. 我对这类工具的一点个人判断折腾完这一圈我对openrig这类“AI 编码工具装配器”有个比较明确的判断它的价值不在技术难度而在把隐性知识显性化。装 Claude Code、配 Codex、切镜像源、改执行策略这些事单拎出来都不难但组合起来就是一道劝退新人的墙。openrig把这道墙拆成了可复现的步骤这就是它的意义。如果你现在正被npm.ps1 无法加载或者模型端点连不通卡住我的建议是别急着换工具先把排查链路走一遍。大部分问题都不是工具本身的 bug而是环境配置的连锁反应。把 PowerShell 策略、镜像源、PATH 这三样理顺你会发现后面的事情顺得超出预期。至于要不要现在就上openrig我的看法是如果你只是自己用一台机器手动配一次也够但如果你要管多台机器、要带团队、要频繁切换环境那这类装配工具带来的复现性和可维护性值得你花时间投入。配置这东西写一次省一百次前提是你把它写对了。