openrig 配置实战：用 YAML 声明式编排 Claude Code 与 Codex CLI 环境

1. openrig 到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了 open rig。rig 在工程语境里通常指装配、搭建一套可运行的环境比如一台矿机、一套测试台架、一套开发工作台。所以openrig从命名上就带着一个很明确的意图把某套原本需要手动拼装的东西做成开放、可复用、可一键拉起的装备架。结合热搜词里高频出现的claude code、codex、yaml、cli这几个关键词我基本能判断出openrig的定位——它大概率是一个围绕 AI 编码助手coding agent的环境编排与配置管理工具。也就是说它要解决的不是模型好不好用而是我怎么把 Claude Code、Codex CLI 这类工具连同它们的配置、模型接入、代理转发、项目规则文件一次性装配好并且能在不同机器上复现。这个需求真实吗非常真实。我自己在过去大半年里至少在三台机器上反复装过 Claude Code 和 Codex CLI每次都要重新处理一堆东西Node 版本、全局安装路径、API 端点配置、本地模型接入比如 LM Studio、YAML 规则文件、VS Code 插件联动。装一次半小时踩坑两小时。openrig想干的就是把这套装配流程从口头经验变成可版本化的配置文件。所以这篇文章我不打算把它写成一份干巴巴的 README 翻译。我想从一个真实从业者会怎么用 openrig 这类工具的角度把它的核心逻辑、配置思路、实操步骤、以及那些文档里不会写的坑全部摊开讲清楚。不管你是刚接触 Claude Code 的新手还是已经在用 Codex CLI 折腾本地模型的老手应该都能从里面找到能直接抄作业的部分。说明由于openrig的公开资料相对有限下文涉及的具体配置字段、目录结构、命令名称部分是基于同类 CLI 编排工具的常见实践做的合理推演。我会在关键处标注哪些是通用做法哪些是需要你按实际版本核对的地方避免你照抄出错。2. 为什么环境装配这件事值得单独做个工具2.1 手动装 Claude Code 和 Codex 的真实痛点先说 Claude Code。它的安装方式看着简单一条 npm 全局安装命令就完事但真正麻烦的是安装之后。你要处理登录态、要处理它调用终端命令时的权限、要处理它在不同项目里读取的规则文件。热搜里那条 your organization has disabled claude subscription access for claude code 就是典型症状——装是装上了一登录发现组织策略不允许直接卡死。这类问题不是安装问题是环境与账号策略的匹配问题。再说 Codex CLI。它的坑更集中在接入环节。热搜里 codex 接入 deepseek、codex 无法加载组织设置、the gpt-5.6-sol model is not supported when using codex 这几条全部指向同一个核心矛盾Codex 默认绑定的模型端点和你实际想用的模型端点往往不是一回事。你想让它走本地 LM Studio或者走第三方兼容端点就得改配置、改环境变量、改请求路径。改错一个字段报错信息还特别晦涩。把这两个工具放在一起看痛点就非常清晰了痛点类型具体表现手动处理的代价安装一致性不同机器 Node 版本、全局路径不同每台机器重新试错配置分散环境变量、配置文件、项目规则文件三处分离容易漏改、难追溯模型接入端点、密钥、模型名三者必须匹配报错信息不直观排查慢团队协作新人入职要重复一遍所有步骤口头传授无法版本化回滚困难改坏了不知道改回哪一步只能凭记忆恢复openrig这类工具的价值就是把这五类痛点收敛到一份声明式配置里。你描述我要什么工具负责怎么装出来。这跟 Docker Compose 解决服务编排、Ansible 解决服务器配置是同一个思路只不过对象换成了 AI 编码助手。2.2 声明式配置相比脚本的优势在哪有人会说我写个 shell 脚本不也能一键装吗能但脚本和声明式配置有本质区别。脚本是过程式的第一步做什么、第二步做什么顺序写死。问题是环境是有状态的第二次跑脚本时第一步可能已经执行过了你得自己写一堆if判断是否已安装。脚本越写越长最后变成一坨没人敢改的意大利面。声明式配置是目标式的我只声明最终状态应该是什么样工具自己去 diff 当前状态和目标状态只补差量。这就是为什么yaml会成为这类工具的首选配置格式——它天生适合描述结构化的目标状态层级清晰人能读机器也能解析。热搜里 yolov10 yaml 文件怎么创建、rstudio 的 yaml 在哪里 这些看似不相关的词其实反映了一个共性YAML 已经成了跨领域描述配置的通用语言。从深度学习模型定义到 IDE 设置大家都在用 YAML。openrig选择 YAML 作为配置载体是顺应这个趋势的。2.3 openrig 在工具链里的位置我倾向于把openrig理解成工具链里的装配层它上面是具体的 AI 编码助手Claude Code、Codex CLI下面是操作系统和运行时Node、Python、终端。它的职责边界大概是管安装哪些工具、装什么版本、装到哪配每个工具的配置文件、环境变量、模型端点连工具之间怎么协作比如 VS Code 插件怎么指向 CLI复现换台机器一份配置拉起同样的环境它不该管的是模型本身的能力、你的业务代码逻辑、账号的权限策略。这些是边界外的事指望 openrig 解决 organization disabled access 这种账号策略问题是不现实的它只能帮你把配置摆对策略得你自己去账号后台处理。3. 一份 openrig 配置该怎么写3.1 配置文件的基本骨架假设openrig的配置入口是一个openrig.yaml具体文件名以实际版本为准它的骨架大概长这样。我先给一个结构再逐段解释为什么这么设计version: 1 runtime: node: 20.x package_manager: npm tools: claude-code: enabled: true install: global config: theme: dark auto_approve: false codex-cli: enabled: true install: global config: model: local endpoint: http://127.0.0.1:1234/v1 models: local: provider: lmstudio base_url: http://127.0.0.1:1234/v1 model_name: your-local-model workspace: rules_file: .openrig/rules.md vscode: integrate: true这个骨架里我刻意把配置分成了四层runtime运行时、tools工具、models模型接入、workspace工作区。分层的好处是关注点分离——运行时出问题只查 runtime模型连不上只查 models不用在一大坨配置里大海捞针。3.2 runtime 层为什么 Node 版本要锁死runtime层看起来最简单其实最容易埋雷。Claude Code 和 Codex CLI 都是 Node 生态的工具对 Node 版本有隐性要求。我踩过的坑是系统默认 Node 是 18装完工具能跑但某些依赖在 18 上行为不一致偶尔报奇怪的错。换成 20 之后一切正常。所以配置里显式锁 Node 版本不是多此一举而是把隐性依赖变成显性声明。这样换机器时工具会先检查 Node 版本不匹配就提示你而不是让你在运行时报错时一脸懵。package_manager字段同理。npm、pnpm、yarn 在全局安装路径、软链接行为上有差异。团队里如果有人用 pnpm、有人用 npm装出来的全局命令位置可能不一样导致我这能跑你那不能跑。统一声明省掉这类扯皮。实操心得如果你的机器上已经有多个 Node 版本比如通过 nvm 管理建议在 openrig 配置里明确写版本号而不是写latest。latest看着省事但某天上游发新版你的环境就被动升级了可能直接跑不起来。锁版本是稳定性的第一道防线。3.3 tools 层安装方式与配置项的分离tools层是核心。我把它设计成安装方式和配置内容两个子块是有讲究的。install: global表示全局安装。为什么不用项目本地安装因为 Claude Code、Codex CLI 这类工具的使用场景是跨项目的——你在 A 项目里想用在 B 项目里也想用装成全局命令最方便。项目本地安装适合那种只在特定项目里用的工具编码助手不属于这类。config子块里放的是工具自身的配置。这里有个关键认知不同工具的配置项差异很大openrig 不可能穷举所有字段。所以好的设计应该是透传——你在 config 里写什么工具就原样写进对应工具的配置文件。这样即使工具升级加了新配置项你也不用等 openrig 更新直接写进去就行。以 Claude Code 为例它常见的配置诉求包括主题、是否自动批准命令执行、默认模型、规则文件路径。其中是否自动批准这个开关特别值得说。关掉它每次执行终端命令都要你确认安全但烦打开它效率高但风险大。我的建议是新手阶段关掉熟悉之后再按项目开。因为 Claude Code 是真的会执行终端命令的热搜里 claude code 如何直接执行终端命令 就是在问这个能力。让它自动执行等于给它一把没保险的枪。3.4 models 层本地模型接入的字段匹配陷阱models层是坑最多的地方没有之一。热搜里 claude code 调用 lmstudio 的本地模型、codex 接入 deepseek 这些需求全部落在这个层。接入本地或第三方模型核心就三个字段base_url、model_name、以及可能的api_key。看起来简单但三者必须严格匹配错一个就连不上。base_url必须指向兼容 OpenAI 接口格式的端点。LM Studio 默认在http://127.0.0.1:1234/v1注意结尾的/v1不能少少了就 404。model_name必须是端点实际加载的模型名不是你随便起的名字。LM Studio 里加载的模型名和你在配置里写的必须一字不差。api_key对于本地模型通常随便填一个非空字符串即可但不能留空很多客户端会因为空 key 直接拒绝请求。我见过太多人卡在明明端点通了就是报错最后发现是模型名写错了大小写或者 base_url 多了个斜杠。这类问题没有捷径就是逐个字段核对。字段常见错误正确做法base_url漏掉/v1后缀完整写http://127.0.0.1:1234/v1model_name用了自己起的别名用端点返回的真实模型 IDapi_key留空填任意非空字符串endpoint 路径用了/responses而非/chat/completions按客户端要求选对路径热搜里那条 cc switch local proxy failed while handling codex endpoint /responses 特别典型——它说明 Codex 在某些模式下走的是/responses路径而不是常见的/chat/completions。如果你的本地端点不支持/responses就会失败。这时候要么换支持该路径的端点要么在配置里把路径改对。路径不匹配是本地模型接入失败的头号原因。3.5 workspace 层规则文件与编辑器联动workspace层管的是项目级的东西。rules_file指向一个规则文件里面写的是你希望 AI 助手遵守的项目约定——比如代码风格、目录结构、禁止修改的文件。这个文件相当于给 AI 的项目说明书。为什么规则文件要单独抽出来因为它是跨工具复用的。Claude Code 读它Codex CLI 也读它将来换个新工具还能读它。把规则和工具解耦你的项目约定就不会被某个工具的私有格式绑架。vscode.integrate这个开关对应热搜里 vscode 配置 claude code、claude code for vs code 的需求。编辑器联动的本质是让编辑器里的 AI 面板指向你配置好的 CLI 后端。这样你在编辑器里敲的指令实际是 CLI 在跑用的是你 openrig 里配好的模型和规则。联动配好了体验是在编辑器里用 AI配不好就是编辑器插件和 CLI 各玩各的。4. 从零跑通 openrig 的完整流程4.1 前置检查别急着装先看这三样很多人一上来就install结果卡在第一步。我的习惯是先做前置检查确认三件事第一Node 和包管理器是否就位。跑一下node -v和npm -v确认版本符合配置要求。如果版本不对先解决版本问题别硬装。第二目标模型端点是否可达。如果你要接本地模型先确认 LM Studio 之类的服务已经启动并且用curl测一下端点通不通curl http://127.0.0.1:1234/v1/models能返回模型列表说明端点活着。返回连接拒绝说明服务没起或者端口不对。这一步能帮你排除掉一半的接入失败问题。第三账号与权限状态。Claude Code 这类工具需要登录登录前确认你的账号策略允许使用。热搜里 your organization has disabled claude subscription access 就是策略问题这种问题在配置层面无解必须先去账号后台确认。注意前置检查花五分钟能省掉后面半小时的瞎折腾。我见过太多人跳过这步然后在报错里反复横跳。4.2 初始化配置从模板到可用前置检查过了开始初始化。如果 openrig 提供init命令跑一下生成模板openrig init它会生成一份带注释的openrig.yaml。不要直接删注释那些注释是字段说明留着能帮你少查文档。然后按上一节的骨架逐层填。填的时候有个技巧先填最小可用配置跑通再加东西。什么叫最小可用就是只配一个工具、一个模型能跑起来就行。跑通之后再逐步加第二个工具、加编辑器联动、加规则文件。这样出问题时你能确定是新加的那部分导致的而不是在一堆配置里猜。我见过有人一上来就把所有功能全配上结果跑不起来根本不知道是哪块的问题。增量式配置是排错友好的做法。4.3 执行装配观察输出别只看结果配置填好执行装配openrig apply这时候别只盯着最后那句 success要看中间的输出。好的工具会打印每一步做了什么检查 Node 版本、安装工具、写入配置、验证端点。这些中间输出是你排错的线索。如果某一步失败输出通常会告诉你失败在哪。比如Node 版本不匹配、端点不可达、配置文件写入失败。根据提示定位比盲目重试高效得多。装配完成后验证一下工具是否真的可用claude --version codex --version能打印版本号说明命令已经进 PATH 了。如果提示 command not found多半是全局安装路径没进 PATH需要手动加一下或者重开终端。4.4 验证模型接入一次真实的请求工具装好了不代表模型接通了。最可靠的验证方式是发一次真实请求。在 Claude Code 或 Codex CLI 里让它执行一个最简单的任务比如列出当前目录的文件。如果它能正常响应说明整条链路通了CLI → 配置 → 端点 → 模型 → 返回。如果报错根据错误信息定位报连接失败端点问题回去查 base_url 和服务状态报模型不存在model_name 写错了报认证失败api_key 问题报路径不支持endpoint 路径问题参考 3.4 节的表格这套排查链路我用了很多次基本能覆盖 90% 的接入问题。5. 那些文档不会告诉你的坑5.1 全局安装的 PATH 陷阱全局安装最隐蔽的坑是 PATH。npm 全局安装的命令会放到一个特定的全局 bin 目录这个目录不一定在系统 PATH 里。表现就是安装显示成功但敲命令提示找不到。排查方法npm config get prefix这个命令会打印全局安装前缀命令实际在prefix/bin下。确认这个路径在 PATH 里不在就加上。加完记得重开终端或者source一下配置文件。这个坑之所以隐蔽是因为它因环境而异。有人机器上默认就配好了有人就没有。所以换机器时PATH 是必查项。5.2 配置文件优先级谁覆盖谁当你有多个层级的配置时全局配置、项目配置、环境变量优先级就成了关键问题。常见规则是环境变量 项目配置 全局配置。但不同工具实现不一样有的反过来。我踩过的坑是在全局配置里改了模型端点但项目配置里还留着旧的结果一直走旧端点怎么改全局都没用。后来才发现是项目配置优先级更高。排查这类问题的通用方法把配置逐层注释掉看行为变化。哪一层注释掉之后行为变了说明那一层在生效。笨办法但管用。5.3 本地模型的并发与超时本地模型比如跑在 LM Studio 里的和云端模型有个本质区别本地资源有限。云端模型你并发十个请求它扛得住本地模型可能第二个请求就开始排队甚至超时。表现就是单个请求正常一旦 AI 助手连续发多个请求比如它要读多个文件就开始卡顿或报超时。应对办法有两个一是调大超时时间在配置里把 timeout 设长一点二是限制并发如果工具支持的话。另外本地模型的上下文窗口通常比云端小喂太多内容进去会直接失败这点也要注意。5.4 规则文件被忽略的几种情况规则文件写了但 AI 助手好像没读这是常见困惑。原因通常有几种一是路径不对。规则文件的路径是相对于项目根目录还是相对于配置文件不同工具定义不同。写错了就找不到。二是文件名不对。有的工具认.rules有的认rules.md有的认特定目录下的文件。得按工具要求来。三是格式不对。规则文件如果是 Markdown工具可能只解析特定结构如果是纯文本可能要求特定分隔符。格式不对内容就读不进去。排查方法故意在规则文件里写一条很显眼的规则比如所有回复必须以特定词开头然后测试 AI 是否遵守。遵守了说明读到了没遵守说明没读到再回去查路径和格式。5.5 版本升级后的配置失效工具升级后配置失效是另一个高频坑。工具发新版可能改了配置字段名、改了默认行为、改了文件位置。你原来的配置在新版上可能直接不认。应对策略升级前先备份配置升级后对比新旧版本的配置要求通常 release notes 里会写 breaking changes。如果配置失效按新版要求改。别指望配置能跨大版本无缝迁移。6. 把 openrig 用进团队协作6.1 配置入库让环境可版本化openrig最大的团队价值是让环境变成可以进 Git 的东西。把openrig.yaml提交到仓库新人 clone 下来跑一条openrig apply环境就装好了。这比写一份新人入职环境搭建文档靠谱得多——文档会过期配置文件不会。但要注意配置文件里不能放密钥。api_key 这类敏感信息应该通过环境变量注入或者放在不入库的本地文件里。配置里只写从环境变量读 key不写 key 本身。6.2 规则文件共享统一团队 AI 行为规则文件入库能让团队里所有人的 AI 助手遵守同一套约定。比如统一要求提交信息用中文、不要动 vendor 目录、测试文件放在 tests 下。这样不管谁用 AI 生成代码风格都是一致的。这解决了一个隐性痛点AI 生成的代码风格因人而异。同一个人用不同工具风格都可能不一样。有了共享规则文件风格就被约束住了。6.3 多环境配置开发机与 CI 的差异团队里通常有开发机和 CI 环境。两者对 AI 助手的需求不同开发机要交互式使用CI 里可能只需要跑自动化任务。openrig支持多环境配置的话可以定义dev和ci两套 profile各自启用不同的工具和配置。开发机启用编辑器联动CI 里关掉开发机接本地模型CI 里接云端端点。一套配置两种形态。如果工具不支持 profile退而求其次的办法是用不同的配置文件通过命令行参数指定用哪份。虽然土但能用。7. 我实际用下来的一些体会折腾openrig这类工具我最大的体会是它省的不是安装时间是排错时间。安装本身可能就十分钟但配置不对导致的排错动辄一两个小时。把配置声明化、版本化之后排错从凭记忆猜变成对着配置查效率提升是数量级的。另一个体会是别追求一步到位。我一开始想把所有工具、所有模型、所有联动全配齐结果配置复杂到自己都看不懂出问题根本没法定位。后来改成增量式先跑通一个最小闭环再逐步加反而更快到达全功能可用的状态。还有一点本地模型接入这件事耐心比技巧重要。字段匹配、路径、模型名任何一个不对都连不上而且报错信息往往不直观。这时候别急着换工具先把三个核心字段逐个核对一遍八成问题就解决了。最后分享一个我常用的小技巧在配置里给每个工具加一个notes字段如果工具支持透传的话写一句这个工具是干嘛的、为什么这么配。过几个月回头看配置这句备注能帮你快速回忆起当时的决策比翻 Git 历史快得多。配置是给人看的不只是给机器执行的。