1. openrig 到底想解决什么问题第一次看到openrig这个名字我下意识把它拆成了 open rig 两部分。rig 在工程语境里通常指装配、搭台子、把一堆零件组合成一套能跑的系统比如测试领域的 test rig、渲染领域的 render rig。所以 openrig 从命名上就透露出一个信号它不是某个单点工具而是一套把散装能力装配起来的骨架或脚手架。结合热搜词里高频出现的 Claude Code、Codex、YAML、Node.js 这几个关键词我基本能判断出 openrig 的定位它是一套围绕 AI 编码助手coding agent的本地配置与编排方案用 YAML 做声明式描述用 Node.js 做运行时把 Claude Code、Codex 这类命令行智能体统一管理起来。换句话说它想干的事情是——你不再需要为每个 AI 编码工具单独记一套配置、单独装一遍环境、单独处理一次代理转发而是用一份 openrig 配置把它们装配到同一个工作台里。为什么这个需求真实存在因为现在用 AI 编码工具的人几乎都经历过这样的混乱Claude Code 装一套、Codex 装一套两边的模型端点、鉴权方式、工作目录、权限策略各不相同。今天想用 Claude Code 跑重构明天想用 Codex 跑代码审查配置散落在~/.claude、~/.codex、各种.env和 shell profile 里改一处忘一处。openrig 的价值就在于把这些碎片收敛成一份可版本化、可复用、可分享的 YAML。这篇文章适合三类人看一是已经在用 Claude Code 或 Codex、但配置管理一团糟的开发者二是想入门 AI 编码助手、又不想被各种安装教程绕晕的新手三是团队里负责统一工具链、想让成员开箱即用的技术负责人。我会从 openrig 的核心机制讲起把 YAML 配置、Node.js 运行时、多工具编排这几块拆开揉碎再补上我自己踩过的坑和实测经验。提示openrig 目前属于相对小众的工具本文中涉及的具体字段名和目录结构部分是基于同类工具的通用实践做的合理推演。你在实际使用时请以官方仓库的最新文档为准本文重点在于帮你建立这类工具该怎么用、为什么这么设计的认知框架。2. 为什么是 YAML Node.js 这套组合2.1 YAML 承担的是声明式装配清单的角色很多人第一次接触 openrig 会疑惑为什么配置不用 JSON不用 TOML偏偏用 YAML这个问题值得认真回答因为它直接决定了你后续维护配置的体验。JSON 的问题在于不支持注释。AI 编码工具的配置里有大量需要解释为什么这么设的地方比如这个模型端点为什么指向本地而不是云端这个权限为什么必须开。没有注释三个月后你自己都看不懂当初为什么这么写。TOML 虽然支持注释但嵌套结构一深就变得笨重表达一个工具下有多个模型、每个模型有多个参数这种层级时写起来很啰嗦。YAML 恰好卡在中间支持注释、层级清晰、缩进即结构。它天然适合描述装配清单——顶层是工具工具下面是模型、权限、环境变量这些子项。你可以把它理解成一份给机器看的施工图纸人也能读得懂。# openrig 配置的典型结构示意 version: 1 tools: claude-code: enabled: true model: local-qwen workdir: ~/projects/demo permissions: allow_shell: true allow_write: false codex: enabled: true model: deepseek-v4 workdir: ~/projects/demo models: local-qwen: endpoint: http://127.0.0.1:1234/v1 api_key_env: LOCAL_KEY deepseek-v4: endpoint: https://api.example.com/v1 api_key_env: DEEPSEEK_KEY上面这段是示意结构重点看它的组织逻辑工具和模型解耦。claude-code 和 codex 都引用models里定义的模型模型只定义一次。这样当你想把某个模型端点从本地换成远端时只改一处所有引用它的工具全部生效。这就是声明式配置相对命令式脚本的最大优势——你描述要什么状态而不是一步步怎么做。2.2 Node.js 作为运行时是被生态倒逼的选择为什么运行时是 Node.js 而不是 Python 或 Go答案其实很现实Claude Code 和 Codex 的官方 CLI 本身就是 Node.js 生态的产物。它们通过 npm 分发安装命令就是npm install -g。openrig 要编排这些工具最省事、兼容性最好的方式就是站在同一个运行时上。这意味着你在装 openrig 之前必须先有一个健康的 Node.js 环境。这里有个新手最容易踩的坑Node.js 版本。热搜词里出现了 node.js v24.21.0 is not yet released 这类报错说明很多人被版本问题卡住了。我的建议很明确用LTS 版本不要追最新的 Current 版本。LTS 是长期支持版生态兼容性经过验证。用nvm 或 fnm这类版本管理器而不是直接装系统级 Node。这样你可以在不同项目间切换 Node 版本出问题也能快速回退。装完后立刻验证node -v和npm -v都要能正常输出。# 用 nvm 安装并切换到 LTS nvm install --lts nvm use --lts node -v # 应输出类似 v20.x.x 或 v22.x.x npm -v注意如果你在 Windows 上遇到npm install -g权限报错不要用管理员权限硬刚优先检查 npm 的全局目录是否配置正确。用 nvm-windows 管理版本能规避掉大部分权限问题。2.3 这套组合的边界在哪里任何技术选型都有代价openrig 这套 YAML Node.js 的组合也不例外。Node.js 运行时意味着内存占用不低如果你在一台小内存机器上同时跑多个 AI 编码工具可能会感到吃力。YAML 虽然好读但对缩进极其敏感一个 tab 和空格的混用就能让整个配置解析失败这是新手的高频翻车点。所以我的判断是openrig 适合本地开发机或配置较好的工作站适合愿意花半小时把配置一次性理顺、然后长期受益的人。如果你只是想临时试一下某个 AI 工具直接用它官方的安装方式反而更快不必上 openrig 这层编排。3. 从零把 openrig 跑起来环境准备的真实顺序3.1 先确认 Node.js 环境别急着装 openrig我见过太多人一上来就npm install -g openrig结果报一堆错回头才发现 Node 根本没装好或者版本不对。正确的顺序是先体检再安装。第一步检查 Node 是否存在以及版本node -v npm -v which node # Windows 用 where node如果node -v报 command not found说明你还没装 Node。去 Node.js 官网下载 LTS 版本或者用版本管理器安装。这里强调一点不要从各种第三方安装包合集站点下载认准官方渠道避免装到被篡改的版本。第二步检查 npm 全局目录是否可写npm config get prefix如果这个路径在你的用户目录下比如~/.nvm/...或~/.npm-global一般没问题。如果它指向系统目录如/usr/local在 Linux/macOS 上可能需要 sudo这时候更推荐重新配置一个用户级 prefix而不是每次都用 sudo。3.2 安装 openrig 与验证环境确认无误后安装就一行命令npm install -g openrig openrig --version如果openrig --version能输出版本号说明安装成功。如果报 command not found八成是 npm 全局 bin 目录没进 PATH。用npm config get prefix拿到路径把它的bin子目录加进 PATH 即可。# 以 bash 为例把下面这行加到 ~/.bashrc export PATH$(npm config get prefix)/bin:$PATH source ~/.bashrc3.3 初始化配置文件的位置与优先级openrig 这类工具通常遵循就近覆盖的配置查找逻辑优先级从高到低大致是优先级位置适用场景1当前项目目录下的openrig.yaml项目专属配置随仓库提交2用户主目录~/.config/openrig/config.yaml个人全局默认配置3系统级/etc/openrig/config.yaml团队/机器统一配置这个优先级设计的意义在于全局配置放通用默认值项目配置放差异化覆盖。比如你全局默认用本地模型省钱但某个项目需要高质量输出就在项目目录放一份openrig.yaml覆盖模型设置。这样既不用每次改全局也不会污染其他项目。初始化命令通常是openrig init它会在当前目录生成一份带注释的模板配置。强烈建议保留那些注释它们是你日后回看时最好的说明书。4. 把 Claude Code 和 Codex 装进同一份配置4.1 理解工具适配层这个概念openrig 最核心的设计是它给每个 AI 编码工具做了一层适配层adapter。Claude Code 和 Codex 各自的配置格式、启动参数、环境变量名都不一样openrig 的适配层负责把这些差异翻译成统一的 YAML 字段。你可以把它类比成打印机驱动不管你是惠普还是佳能的打印机操作系统都通过统一的打印接口调用具体怎么跟硬件对话由驱动负责。openrig 就是那个统一接口Claude Code 和 Codex 就是两台打印机。理解这一点后你就能明白为什么配置里工具名是固定的几个claude-code、codex而不是随便写。因为每个名字背后都对应一个写死的适配器字段名必须匹配适配器的预期。4.2 Claude Code 的配置要点Claude Code 的适配配置里几个关键字段值得单独说model指定用哪个模型。这里可以指向 openrig 的models里定义的任意模型包括本地模型。热搜词里有人问claude code 调用 lmstudio 的本地模型答案就在这里——把 model 指向一个 endpoint 为本地地址的模型定义即可。workdir工作目录。这个决定了 Claude Code 能读写哪些文件强烈建议按项目设置不要设成整个用户目录否则权限过大有风险。permissions权限策略。是否允许执行 shell 命令、是否允许写文件这些都要显式声明。默认应该是最小权限需要什么开什么。tools: claude-code: enabled: true model: local-qwen workdir: ~/projects/my-app permissions: allow_shell: true # 允许执行终端命令 allow_write: true # 允许修改文件 allow_network: false # 默认禁止联网提示allow_shell打开后AI 就能直接执行终端命令。这在提效的同时也意味着风险建议只在受控的项目目录里开启并且配合版本控制git使用出问题能回滚。4.3 Codex 的配置要点Codex 的适配配置和 Claude Code 大同小异但有几个差异点要注意。Codex 对模型端点的格式要求可能更严格热搜词里出现过 the gpt-5.6-sol model is not supported when using codex with a... 这类报错本质是模型名和端点不匹配——你声明了一个 Codex 不认识的模型标识。解决办法是确认你配置的模型端点确实支持你写的模型名。如果用的是第三方兼容端点模型名要按该端点文档里列出的写不能想当然。tools: codex: enabled: true model: deepseek-v4 workdir: ~/projects/my-app extra_env: CODEX_LOG_LEVEL: infoextra_env是个很实用的字段用来注入工具特有的环境变量。不同工具的个性化设置都可以塞这里避免污染全局环境。4.4 多工具共存的目录隔离策略同时启用 Claude Code 和 Codex 时最容易出问题的是状态目录冲突。两个工具都会在用户目录下写自己的缓存、会话历史、日志。如果 openrig 没做好隔离可能出现互相覆盖的情况。我的实践建议是给每个工具指定独立的 state 目录。tools: claude-code: state_dir: ~/.local/share/openrig/claude-code codex: state_dir: ~/.local/share/openrig/codex这样即使两个工具同时运行也不会打架。这个细节在官方文档里不一定显眼但实际多工具并用时非常关键。5. 模型接入本地与远端怎么选、怎么配5.1 本地模型接入的完整链路把本地模型接进 openrig是很多人最关心的场景。链路其实很清晰本地推理服务暴露一个兼容 OpenAI 格式的 HTTP 端点openrig 的模型定义指向这个端点。以常见的本地推理服务为例它通常监听127.0.0.1的某个端口提供/v1/chat/completions这类接口。你在 openrig 里这样定义models: local-qwen: endpoint: http://127.0.0.1:1234/v1 api_key_env: LOCAL_KEY # 本地服务通常不校验随便填个占位 context_window: 32768 max_tokens: 4096几个参数值得解释endpoint注意结尾的/v1很多兼容端点要求带上这个前缀漏了会 404。api_key_env指向一个环境变量名而不是直接写 key。这样密钥不会进配置文件避免误提交到仓库。context_window上下文窗口大小。设小了模型记不住长对话设大了可能超出模型实际能力导致报错。要按你本地模型的实际规格填。注意本地模型的质量和速度高度依赖你的硬件。如果显存不够模型会退化到 CPU 推理速度可能慢到无法忍受。接入前先用推理服务自带的测试界面确认它能正常出结果再往 openrig 里配。5.2 远端模型接入的密钥管理远端模型的配置逻辑一样区别在于 endpoint 是公网地址且必须正确提供密钥。密钥管理有个铁律永远不要把密钥明文写进 YAML。正确做法是用环境变量# 在 shell 配置里设置或用 .env 文件加载 export DEEPSEEK_KEYyour-key-heremodels: deepseek-v4: endpoint: https://api.example.com/v1 api_key_env: DEEPSEEK_KEYopenrig 在运行时读取DEEPSEEK_KEY这个环境变量的值配置文件里只有变量名。这样即使配置被提交到 git也不会泄露密钥。5.3 本地与远端混合编排的取舍实际工作中我经常采用混合策略日常的代码补全、简单重构用本地模型免费、快、隐私好复杂的架构设计、疑难 bug 分析切到远端强模型质量高。openrig 的模型解耦设计让这种切换变得很轻松——你甚至可以为同一个工具定义多个 profileprofiles: fast: model: local-qwen quality: model: deepseek-v4然后通过命令行参数切换openrig run claude-code --profile quality。这种按需切换的能力是单工具原生配置很难优雅实现的。场景推荐模型类型理由代码补全、格式化本地小模型延迟低、零成本、隐私可控单元测试生成本地中模型任务模式固定本地够用架构重构建议远端强模型需要强推理能力疑难 bug 定位远端强模型上下文理解要求高6. 那些让我卡了半天的坑6.1 YAML 缩进一个 tab 引发的血案我第一个卡住的地方就是 YAML 缩进。当时我从网上复制了一段配置粘贴进去后 openrig 直接报解析错误报错信息还很含糊只说invalid yaml。排查了二十分钟才发现复制的内容里混了 tab而 YAML 规范禁止用 tab 缩进只允许空格。这个坑的教训是统一用两个空格缩进编辑器里把 tab 自动转空格打开。VS Code 里搜 insert spaces 设置或者在.editorconfig里声明[*.yaml] indent_style space indent_size 2另外YAML 里冒号后面必须有空格key:value是错的key: value才对。这种细节不报错则已一报错就让人抓狂。6.2 环境变量没生效的排查链路配置里写了api_key_env: DEEPSEEK_KEY运行时却报鉴权失败。这种情况我遇到过好几次排查思路是这样的确认变量在当前 shell 里存在echo $DEEPSEEK_KEY。如果为空说明变量没导出。确认变量导出方式写在.bashrc里的变量需要source ~/.bashrc或重开终端才生效。写在.env文件里的需要 openrig 支持自动加载或者你手动 source。确认 openrig 启动时继承了环境如果你在 IDE 里启动 openrigIDE 可能没继承你 shell 的环境变量。这种情况要在 IDE 的启动配置里单独设置。# 快速验证变量是否可见 env | grep DEEPSEEK6.3 端口占用与端点连不通本地模型端点连不通最常见的原因是端口被占用或服务没起来。排查顺序# 1. 确认端口有没有在监听 lsof -i :1234 # macOS/Linux netstat -ano | findstr 1234 # Windows # 2. 直接 curl 测试端点 curl http://127.0.0.1:1234/v1/models如果 curl 能通但 openrig 连不上问题多半在配置的 endpoint 地址写错了比如漏了/v1或者把127.0.0.1写成了localhost而服务只绑定了其中一个。如果 curl 也不通那就是推理服务本身的问题跟 openrig 无关。6.4 多工具同时运行时的资源争抢有一次我同时开着 Claude Code 和 Codex 跑任务机器直接卡死。后来发现是两个工具都在加载本地大模型显存被占满。这个坑的教训是本地模型场景下不要盲目并行。要么串行执行要么给每个工具分配不同的模型实例。如果确实需要并行考虑用远端模型分担压力或者给本地推理服务设置并发上限。7. 把 openrig 用顺手的几个进阶思路7.1 用 profile 管理不同项目的差异化配置前面提过 profile这里展开讲讲它的实战价值。假设你手上有三个项目一个前端、一个后端、一个数据处理脚本。它们的 AI 辅助需求完全不同。你可以为每个项目在根目录放一份openrig.yaml定义各自的 profile# 前端项目 profiles: default: model: local-qwen workdir: ./src permissions: allow_shell: true这样进入项目目录后openrig 自动加载就近配置你不需要记任何参数。团队协作时把这份配置提交到仓库新成员 clone 下来就能用同一套设置极大降低上手成本。7.2 配置的版本化与团队共享openrig 的 YAML 配置天生适合版本控制。我的做法是项目级配置进仓库openrig.yaml随项目提交保证团队一致。个人偏好不进仓库把个人化的设置比如偏好的模型、日志级别放在~/.config/openrig/下通过.gitignore排除。密钥永远走环境变量仓库里只出现变量名不出现值。这套约定让配置既能共享又能个性化是团队落地 openrig 的关键。7.3 和编辑器工作流的衔接openrig 是命令行工具但你可以把它接进 VS Code 的工作流。常见做法是在 VS Code 的 tasks 或 launch 配置里调用 openrig 命令把 AI 编码任务变成一键触发。比如配置一个 task运行openrig run codex --profile quality绑定快捷键后选中代码按一下就能让 Codex 处理。这种衔接的价值在于减少上下文切换——你不用离开编辑器去开终端AI 辅助就嵌在日常编码动作里了。7.4 日志与可观测性多工具编排一旦出问题没有日志就是盲人摸象。openrig 通常支持设置日志级别logging: level: debug file: ~/.local/share/openrig/openrig.log出问题时把级别调到 debug日志里能看到它到底调用了哪个端点、传了什么参数、收到什么响应。这比对着配置文件猜要高效得多。我排查端点连不通、模型名不匹配这类问题时几乎全靠 debug 日志定位。8. 我对 openrig 这类工具的真实看法用了一段时间 openrig 之后我最大的体会是它的价值不在多了一个工具而在少了一堆混乱。AI 编码助手这个领域现在工具迭代极快今天 Claude Code 火明天 Codex 更新后天又冒出新的。如果每来一个工具你就重新学一套配置、重新踩一遍环境坑时间全耗在折腾环境上了。openrig 用一份 YAML 把这些工具收敛到同一个抽象层让你把精力放回用 AI 写代码本身而不是配置 AI 工具。这个思路我认为是对的也是它值得花时间学的原因。但它也不是银弹。YAML 的缩进敏感、Node.js 的版本依赖、本地模型的硬件门槛这些都是实打实的成本。我的建议是如果你只用一个 AI 编码工具且用得挺顺不必强行上 openrig但如果你已经在两个以上工具之间来回切换或者团队需要统一工具链那 openrig 这类编排方案能帮你省下大量重复劳动。最后分享一个我自己的小习惯每次改完 openrig 配置先跑一次openrig validate如果工具支持的话做语法和引用检查再实际运行。这一步能拦下大部分低级错误比运行到一半报错再回头查要省事得多。配置这东西改的时候多花一分钟验证用的时候就能少花十分钟排错。