1. openrig 到底在解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目比如机械臂或者开源云台。但结合 Claude Code、Codex、YAML、npm 这几个关键词放在一起方向就很清楚了——这是一个围绕 AI 编程助手做配置编排与运行环境管理的工具。说白了它要处理的是这样一个场景你手头同时有 Claude Code、Codex 这类命令行 AI 编程工具每个工具有自己的配置文件、模型端点、参数体系切换一次要改一堆东西时间长了配置散落各处谁也记不清哪个版本对应哪个项目。openrig 想做的就是把这些零散的配置收拢到一套统一的 YAML 描述里用一条命令完成环境装配。我自己的日常就是 Claude Code 和 Codex 混着用。Claude Code 在长上下文重构任务上顺手Codex 在处理某些特定端点和响应格式时更稳但两者的配置逻辑完全不一样。Claude Code 走的是订阅鉴权和本地配置目录Codex 走的是 endpoint 加模型名的组合中间还夹着 npm 全局包版本、Node 环境变量、PowerShell 执行策略这些坑。每次换机器或者重装环境我都要花小半天把这些重新捋一遍。openrig 这类工具的价值就在这儿把环境搭建这件事从手工活变成可版本化、可复现的声明式配置。它适合的人群也很明确。如果你只是偶尔用一下某个 AI 编程工具那确实没必要上这套东西。但如果你属于下面几种情况openrig 的思路就值得认真研究一是团队里多人共用一套 AI 编程工作流需要保证每个人环境一致二是你经常在不同项目间切换每个项目对模型、端点、上下文长度的要求不同三是你在 Windows 上折腾过 npm 全局包和 PowerShell 脚本策略被那些报错折磨过。这几种场景下一套统一的 YAML 编排能省掉大量重复劳动。需要先说明的是openrig 目前并不是一个已经高度成熟、文档齐全的官方项目更多是社区里围绕 AI 编程工具链自发形成的一类编排实践。所以下面讲的内容一部分是基于它公开的设计思路一部分是我在实际搭建类似环境时总结出来的通用方法。你在参考的时候重点看思路和排查方法具体命令以你本地实际版本为准。2. 整体设计思路与方案选型2.1 为什么用 YAML 做配置中枢选 YAML 而不是 JSON 或者 TOML是有实际考量的。JSON 不支持注释你没法在配置里写这行是为了兼容某个旧端点TOML 虽然可读性好但嵌套结构表达起来比较啰嗦。YAML 在可读性和表达力之间取了个平衡支持注释、支持多行字符串、支持锚点和引用这几点对配置文件来说很关键。举个实际例子。Claude Code 和 Codex 的配置里都有模型这个概念但字段名和取值方式不同。用 YAML 的锚点机制你可以定义一份公共的模型参数然后在两个工具的配置块里分别引用改一处就全改。这种复用能力在 JSON 里要靠工具自己实现YAML 原生就有。# 公共模型参数定义 model_defaults: model_defaults temperature: 0.2 max_tokens: 8192 timeout: 120 claude_code: : *model_defaults model: claude-sonnet context_window: 200000 codex: : *model_defaults model: gpt-5.6-sol endpoint: /responses上面这段就是 YAML 锚点的典型用法。model_defaults定义锚点*model_defaults引用它:把整个映射合并进来。这样 temperature、max_tokens 这些公共参数只维护一份两个工具各自只写差异部分。这是 JSON 做不到的也是 openrig 选择 YAML 的核心原因之一。2.2 编排层与执行层分离openrig 的设计里有一个很重要的分层YAML 只负责描述应该是什么样真正去改文件、装包、设环境变量的动作交给执行层。这个分离带来的好处是配置文件可以进版本控制可以 code review可以回滚而执行动作是幂等的——跑一遍和跑十遍结果一样。我见过不少人把配置和脚本混在一起写一个 shell 脚本里既有export又有npm install还有sed改文件最后脚本本身变成了不可读的黑盒。openrig 这种声明式配置 命令式执行的组合本质上是把 Terraform 那套思路搬到了 AI 编程工具的环境管理上。你描述期望状态工具负责收敛到那个状态。这个思路的代价是执行层要处理各种边界情况。比如 npm 全局包已经装了但版本不对是重装还是跳过PowerShell 执行策略被禁用了是报错还是尝试修改这些判断逻辑都在执行层YAML 里不用管。所以你在写 YAML 的时候可以保持干净但排查问题的时候要理解执行层做了什么。2.3 多工具共存的冲突处理Claude Code 和 Codex 装在同一台机器上冲突点比想象中多。最典型的是 npm 全局包路径冲突两个工具如果都依赖某个公共包但版本要求不同npm 的扁平化安装策略就会出问题。还有环境变量冲突比如ANTHROPIC_API_KEY和OPENAI_API_KEY这类虽然名字不同但如果你的编排脚本里用了通用的变量名做中转就容易串。openrig 的处理方式是在 YAML 里为每个工具划分独立的命名空间执行层在应用配置时按命名空间隔离环境变量和文件路径。这个设计看起来简单但实际写配置的时候要注意不要把某个工具的专属参数写到公共块里。我踩过一次坑把max_tokens写进了公共锚点结果 Claude Code 那边正常Codex 那边因为端点对 token 上限有额外限制一直报错。后来把这类有工具特异性的参数拆出来单独写问题就没了。提示公共锚点里只放真正通用的参数比如超时、重试次数。凡是和具体模型、具体端点绑定的参数一律拆到各自的命名空间里别图省事。3. 核心细节解析与实操要点3.1 环境前置检查清单在动手写 openrig 配置之前有几项环境状态必须先确认。这些不是可选项任何一项不满足后面都会以各种奇怪的报错形式冒出来。第一项是 Node 和 npm 的版本。Claude Code 和 Codex 对 Node 版本有要求太老的版本会在安装阶段就失败。用node -v和npm -v确认建议 Node 18 以上。第二项是 npm 全局包目录是否在 PATH 里。很多人装完 Node 之后npm install -g能成功但装完的命令行工具敲不出来就是因为全局 bin 目录没进 PATH。第三项是 Windows 上的 PowerShell 执行策略这个后面单独讲。检查项命令期望结果Node 版本node -vv18.x 及以上npm 版本npm -v9.x 及以上全局包路径npm config get prefix路径存在且在 PATH 中执行策略Get-ExecutionPolicyRemoteSigned 或 Unrestricted这张表建议你照着跑一遍。尤其是最后一项Windows 用户十有八九会在这里卡住。3.2 npm 全局安装的路径陷阱npm install -g装完之后命令找不到这个问题我遇到过太多次。根因是 npm 的全局 prefix 目录和系统 PATH 不一致。你可以用npm config get prefix看当前 prefix 指向哪里然后确认这个路径下的bin子目录Windows 上是根目录本身有没有在 PATH 里。如果不在有两个解决方向。一是把 prefix 改到一个已经在 PATH 里的目录比如npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm这个路径通常装 Node 时就加进 PATH 了。二是手动把当前 prefix 加到 PATH但改完要重启终端才生效。我一般推荐第一种因为改 prefix 是一次性的加 PATH 每次换终端都可能忘。还有一个隐蔽的坑如果你之前用管理员权限装过全局包后来又用普通权限装两个 prefix 可能不一样导致同一个工具装了两份敲命令时执行的是旧的那份。排查方法是where 命令名Windows或which 命令名macOS/Linux看实际执行的是哪个路径下的文件。3.3 PowerShell 脚本执行策略的处理Windows 上跑 npm 相关命令时最常见的报错就是那句无法加载文件 npm.ps1因为在此系统上禁止运行脚本。这不是 npm 坏了是 PowerShell 默认的执行策略太严格不允许运行任何脚本文件。解决办法是改执行策略。以管理员身份打开 PowerShell运行Set-ExecutionPolicy RemoteSigned然后确认。RemoteSigned 的含义是本地写的脚本可以跑从网络下载的脚本需要签名。这个级别对开发环境来说够用也比 Unrestricted 安全。改完之后如果还是报错检查一下是不是在 VSCode 的内置终端里跑。VSCode 终端有时候会继承一个不同的执行策略上下文重启 VSCode 或者手动在终端里再设一次通常能解决。另外如果你用的是公司电脑执行策略可能被组策略锁死这种情况下Set-ExecutionPolicy会提示被覆盖需要联系 IT 处理自己改不了。注意不要为了图省事直接把执行策略设成 Bypass 或者 Unrestricted 全局生效尤其是在共用机器上。RemoteSigned 是开发场景下比较稳妥的选择。3.4 YAML 配置文件的组织结构openrig 的 YAML 配置建议按全局默认 工具命名空间 项目覆盖三层来组织。全局默认放超时、重试、日志级别这类工具命名空间放 Claude Code 和 Codex 各自的模型、端点、鉴权方式项目覆盖放具体项目对上下文长度、工作目录的特殊要求。version: 1 defaults: timeout: 120 retry: 3 log_level: info tools: claude_code: model: claude-sonnet context_window: 200000 config_dir: ~/.claude codex: model: gpt-5.6-sol endpoint: /responses config_dir: ~/.codex projects: my-refactor: tool: claude_code context_window: 1000000 workdir: ./src my-api: tool: codex endpoint: /responses workdir: ./api这个结构的好处是当你切换项目时只需要在projects下面选对应的条目执行层会自动把工具配置和项目覆盖合并。context_window在项目级别覆盖了工具级别的值这就是 YAML 合并的典型应用。注意version字段加版本号是为了将来配置格式升级时能做兼容判断这个习惯建议养成。4. 实操过程与核心环节实现4.1 从零搭建一套可用的 openrig 环境假设你现在是一台干净的 Windows 机器Node 已经装好我们要从零把 Claude Code 和 Codex 都跑起来并用 openrig 的 YAML 统一管理。下面是我实际走通的流程。第一步确认 npm 全局路径并修正。运行npm config get prefix如果输出的是C:\Program Files\nodejs这个路径通常需要管理员权限才能写入普通用户装全局包会失败。改成用户目录下的路径npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm改完关掉终端重开再npm config get prefix确认。然后确认这个路径在 PATH 里没有的话手动加。第二步处理 PowerShell 执行策略。管理员 PowerShell 里跑Set-ExecutionPolicy RemoteSigned确认。这一步做完npm.ps1的报错应该就消失了。第三步安装两个工具。Claude Code 和 Codex 的安装命令以官方当前发布为准通常是 npm 全局安装的形式npm install -g anthropic-ai/claude-code npm install -g openai/codex装完用claude --version和codex --version验证。如果提示命令找不到回到第一步检查 PATH。第四步写 openrig 的 YAML 配置。按 3.4 节的结构先写 defaults 和 tools 两块projects 先留空。把配置文件放在项目根目录命名openrig.yaml。第五步跑一次执行层命令让配置生效。具体命令取决于你用的 openrig 实现版本核心动作是读取 YAML、按命名空间写入各工具的配置目录、设置环境变量。跑完之后分别启动 Claude Code 和 Codex确认能正常连上各自的端点。4.2 模型端点配置的参数计算Codex 的端点配置里有个容易出问题的地方模型名和端点路径必须匹配。热词里出现的the gpt-5.6-sol model is not supported when using codex with a...这个报错根因就是模型名和端点不匹配。Codex 走/responses端点时对模型名有特定要求你写了一个该端点不支持的模型名就会报这个错。排查思路是先确认你用的端点是什么再确认这个端点支持哪些模型名。这两个信息通常在工具的官方文档或者配置示例里。不要凭记忆写模型名模型迭代很快上个月能用的名字这个月可能就变了。参数计算方面max_tokens和context_window的关系要理清。context_window是模型能接受的总上下文长度max_tokens是单次生成的最大输出长度。两者不是一回事。如果你把max_tokens设得接近context_window留给输入的空间就很小了长对话会很快触顶。我的经验值是max_tokens设在context_window的 10% 到 25% 之间具体看任务类型。重构类任务输入长输出短可以设低一点生成类任务反过来。4.3 多项目切换的配置合并逻辑openrig 在项目切换时做的合并顺序是 defaults → tools → projects后面的覆盖前面的。这个顺序很重要因为项目级的配置优先级最高工具级次之全局默认最低。合并的时候有个细节映射类型是深度合并还是浅合并。深度合并会把嵌套的键也逐层合并浅合并只替换顶层键。openrig 这类工具通常用深度合并因为这样项目级只需要写要覆盖的那几个键不用把整个工具配置重写一遍。# tools 里 codex 的配置 codex: model: gpt-5.6-sol endpoint: /responses timeout: 120 # projects 里某个项目只覆盖 timeout my-api: tool: codex timeout: 300深度合并之后这个项目实际生效的 codex 配置是 model 和 endpoint 沿用工具级timeout 用项目级的 300。如果是浅合并整个 codex 块会被替换model 和 endpoint 就丢了。所以你在写项目覆盖的时候要确认工具用的是哪种合并策略不确定的话就把需要的键都写全虽然啰嗦但不会出错。4.4 配置生效的验证方法配置写完不等于生效。我习惯用三步验证第一步让执行层输出合并后的最终配置很多工具支持--dry-run或者--print-config这类参数能看到实际生效的值第二步启动工具后用工具自己的命令查看当前配置比如 Claude Code 有查看当前模型和上下文的命令第三步跑一个最小任务比如让它读一个文件然后回答一个问题确认端点和鉴权都通。这三步里第一步最关键。很多人跳过第一步直接跑任务出错了再回头猜哪里配错了效率很低。能看到合并后的最终配置问题基本一眼就能定位。5. 常见问题与排查技巧实录5.1 npm 相关报错速查npm 的报错信息有时候很误导人同一个现象可能有好几种根因。我整理了一张速查表按报错现象反查原因。报错现象可能原因排查动作npm.ps1 禁止运行脚本PowerShell 执行策略Set-ExecutionPolicy RemoteSigned全局装完命令找不到prefix 不在 PATHnpm config get prefix对比 PATHERESOLVE overriding peer dependency依赖版本冲突看警告里的包名考虑--legacy-peer-deps安装卡住不动源速度慢换国内镜像源装了两份同名工具多 prefix 并存where 命令名看实际路径ERESOLVE这个警告特别常见它本身不一定是错误只是提示某个 peer dependency 被覆盖了。如果安装最终成功了这个警告可以忽略。但如果安装失败就要认真看是哪个包的版本要求冲突了。--legacy-peer-deps能绕过检查但这是权宜之计长期看还是要理顺依赖版本。5.2 端点与模型不匹配的排查前面提到的gpt-5.6-sol model is not supported这类报错排查顺序是先看端点路径对不对再看模型名对不对最后看两者组合是否被支持。这三个是独立的检查点不要混在一起猜。我遇到过一次端点路径写对了模型名也写对了但还是报不支持。最后发现是配置文件里有两处定义了模型名一处是工具级一处是项目级项目级的那个是旧的合并之后覆盖了工具级的新值。这种问题就是配置分散导致的所以我在 3.4 节强调配置要有清晰的组织结构别到处散落。5.3 鉴权失败的几种表现鉴权问题在 Claude Code 和 Codex 上表现不一样。Claude Code 如果订阅鉴权出问题可能提示组织禁用了订阅访问这类信息这时候要检查的是账号状态和订阅配置不是本地环境。Codex 的鉴权失败通常表现为请求被拒或者返回鉴权错误码要检查的是 API key 或者登录状态。这两类问题的排查方向完全不同所以第一步是先判断是鉴权问题还是配置问题。判断方法很简单如果报错信息里出现了账号、订阅、组织、权限这类词往鉴权方向查如果出现的是模型名、端点、格式这类词往配置方向查。5.4 本地模型接入的注意事项热词里有claude code 调用 lmstudio 的本地模型这个场景值得单独说。本地模型接入的核心是把端点指向本地服务比如http://localhost:1234这类地址。但要注意几点本地模型的上下文长度通常比云端模型小很多配置里的context_window要相应调小不然工具会按大窗口去组织请求本地服务处理不了本地模型的响应格式可能和云端不完全一致如果工具对响应格式有严格校验可能会解析失败本地服务的并发能力有限retry和timeout参数要调得保守一些。我实测下来本地模型适合做轻量的代码补全和问答重度的长上下文重构还是得用云端模型。把本地模型配成 fallback云端不可用时顶上这个用法比较实际。5.5 配置回滚与版本管理openrig 的 YAML 配置一定要进版本控制。我见过有人配置改坏了又没有备份只能从头重写。YAML 文件本身是纯文本git 管理起来很方便每次改动都有记录出问题能 diff 出改了什么。建议的做法是主配置进 git本地个性化覆盖用一个单独的openrig.local.yaml这个文件加进.gitignore不提交。执行层读取时先读主配置再读本地覆盖这样团队共享的部分和个人的部分分开既保证一致性又保留灵活性。提示改配置之前先 commit 一次当前状态改完跑验证通过了再 commit。这样任何一次改动出问题都能一键回到上一个可用状态。6. 我踩过的坑和几条实用建议配置管理这件事工具本身只解决一半问题另一半靠使用习惯。我折腾这套东西最大的体会是不要追求一次配到完美先跑通最小可用版本再逐步加东西。一开始就想把所有工具、所有项目、所有参数都配齐结果往往是配置写了一堆一个都没验证通过最后不知道错在哪。另一个体会是关于报错信息的。AI 编程工具的报错有时候很笼统比如只说请求失败不告诉你具体哪一步失败。这时候不要盯着报错本身看要回到配置的合并结果上确认实际生效的值是什么。大部分问题都是配置合并后和预期不一致导致的而不是工具本身有 bug。最后分享一个我常用的小技巧给每个工具配一个健康检查命令就是一条最简单的、能验证端到端通路的命令。每次改完配置先跑健康检查通过了再干正事。这条命令可以是一条简单的问答也可以是一个固定的测试任务。有了它配置改动的影响范围就控制住了不会改一处崩一片。
openrig：用YAML统一编排Claude Code与Codex的AI编程环境
1. openrig 到底在解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目比如机械臂或者开源云台。但结合 Claude Code、Codex、YAML、npm 这几个关键词放在一起方向就很清楚了——这是一个围绕 AI 编程助手做配置编排与运行环境管理的工具。说白了它要处理的是这样一个场景你手头同时有 Claude Code、Codex 这类命令行 AI 编程工具每个工具有自己的配置文件、模型端点、参数体系切换一次要改一堆东西时间长了配置散落各处谁也记不清哪个版本对应哪个项目。openrig 想做的就是把这些零散的配置收拢到一套统一的 YAML 描述里用一条命令完成环境装配。我自己的日常就是 Claude Code 和 Codex 混着用。Claude Code 在长上下文重构任务上顺手Codex 在处理某些特定端点和响应格式时更稳但两者的配置逻辑完全不一样。Claude Code 走的是订阅鉴权和本地配置目录Codex 走的是 endpoint 加模型名的组合中间还夹着 npm 全局包版本、Node 环境变量、PowerShell 执行策略这些坑。每次换机器或者重装环境我都要花小半天把这些重新捋一遍。openrig 这类工具的价值就在这儿把环境搭建这件事从手工活变成可版本化、可复现的声明式配置。它适合的人群也很明确。如果你只是偶尔用一下某个 AI 编程工具那确实没必要上这套东西。但如果你属于下面几种情况openrig 的思路就值得认真研究一是团队里多人共用一套 AI 编程工作流需要保证每个人环境一致二是你经常在不同项目间切换每个项目对模型、端点、上下文长度的要求不同三是你在 Windows 上折腾过 npm 全局包和 PowerShell 脚本策略被那些报错折磨过。这几种场景下一套统一的 YAML 编排能省掉大量重复劳动。需要先说明的是openrig 目前并不是一个已经高度成熟、文档齐全的官方项目更多是社区里围绕 AI 编程工具链自发形成的一类编排实践。所以下面讲的内容一部分是基于它公开的设计思路一部分是我在实际搭建类似环境时总结出来的通用方法。你在参考的时候重点看思路和排查方法具体命令以你本地实际版本为准。2. 整体设计思路与方案选型2.1 为什么用 YAML 做配置中枢选 YAML 而不是 JSON 或者 TOML是有实际考量的。JSON 不支持注释你没法在配置里写这行是为了兼容某个旧端点TOML 虽然可读性好但嵌套结构表达起来比较啰嗦。YAML 在可读性和表达力之间取了个平衡支持注释、支持多行字符串、支持锚点和引用这几点对配置文件来说很关键。举个实际例子。Claude Code 和 Codex 的配置里都有模型这个概念但字段名和取值方式不同。用 YAML 的锚点机制你可以定义一份公共的模型参数然后在两个工具的配置块里分别引用改一处就全改。这种复用能力在 JSON 里要靠工具自己实现YAML 原生就有。# 公共模型参数定义 model_defaults: model_defaults temperature: 0.2 max_tokens: 8192 timeout: 120 claude_code: : *model_defaults model: claude-sonnet context_window: 200000 codex: : *model_defaults model: gpt-5.6-sol endpoint: /responses上面这段就是 YAML 锚点的典型用法。model_defaults定义锚点*model_defaults引用它:把整个映射合并进来。这样 temperature、max_tokens 这些公共参数只维护一份两个工具各自只写差异部分。这是 JSON 做不到的也是 openrig 选择 YAML 的核心原因之一。2.2 编排层与执行层分离openrig 的设计里有一个很重要的分层YAML 只负责描述应该是什么样真正去改文件、装包、设环境变量的动作交给执行层。这个分离带来的好处是配置文件可以进版本控制可以 code review可以回滚而执行动作是幂等的——跑一遍和跑十遍结果一样。我见过不少人把配置和脚本混在一起写一个 shell 脚本里既有export又有npm install还有sed改文件最后脚本本身变成了不可读的黑盒。openrig 这种声明式配置 命令式执行的组合本质上是把 Terraform 那套思路搬到了 AI 编程工具的环境管理上。你描述期望状态工具负责收敛到那个状态。这个思路的代价是执行层要处理各种边界情况。比如 npm 全局包已经装了但版本不对是重装还是跳过PowerShell 执行策略被禁用了是报错还是尝试修改这些判断逻辑都在执行层YAML 里不用管。所以你在写 YAML 的时候可以保持干净但排查问题的时候要理解执行层做了什么。2.3 多工具共存的冲突处理Claude Code 和 Codex 装在同一台机器上冲突点比想象中多。最典型的是 npm 全局包路径冲突两个工具如果都依赖某个公共包但版本要求不同npm 的扁平化安装策略就会出问题。还有环境变量冲突比如ANTHROPIC_API_KEY和OPENAI_API_KEY这类虽然名字不同但如果你的编排脚本里用了通用的变量名做中转就容易串。openrig 的处理方式是在 YAML 里为每个工具划分独立的命名空间执行层在应用配置时按命名空间隔离环境变量和文件路径。这个设计看起来简单但实际写配置的时候要注意不要把某个工具的专属参数写到公共块里。我踩过一次坑把max_tokens写进了公共锚点结果 Claude Code 那边正常Codex 那边因为端点对 token 上限有额外限制一直报错。后来把这类有工具特异性的参数拆出来单独写问题就没了。提示公共锚点里只放真正通用的参数比如超时、重试次数。凡是和具体模型、具体端点绑定的参数一律拆到各自的命名空间里别图省事。3. 核心细节解析与实操要点3.1 环境前置检查清单在动手写 openrig 配置之前有几项环境状态必须先确认。这些不是可选项任何一项不满足后面都会以各种奇怪的报错形式冒出来。第一项是 Node 和 npm 的版本。Claude Code 和 Codex 对 Node 版本有要求太老的版本会在安装阶段就失败。用node -v和npm -v确认建议 Node 18 以上。第二项是 npm 全局包目录是否在 PATH 里。很多人装完 Node 之后npm install -g能成功但装完的命令行工具敲不出来就是因为全局 bin 目录没进 PATH。第三项是 Windows 上的 PowerShell 执行策略这个后面单独讲。检查项命令期望结果Node 版本node -vv18.x 及以上npm 版本npm -v9.x 及以上全局包路径npm config get prefix路径存在且在 PATH 中执行策略Get-ExecutionPolicyRemoteSigned 或 Unrestricted这张表建议你照着跑一遍。尤其是最后一项Windows 用户十有八九会在这里卡住。3.2 npm 全局安装的路径陷阱npm install -g装完之后命令找不到这个问题我遇到过太多次。根因是 npm 的全局 prefix 目录和系统 PATH 不一致。你可以用npm config get prefix看当前 prefix 指向哪里然后确认这个路径下的bin子目录Windows 上是根目录本身有没有在 PATH 里。如果不在有两个解决方向。一是把 prefix 改到一个已经在 PATH 里的目录比如npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm这个路径通常装 Node 时就加进 PATH 了。二是手动把当前 prefix 加到 PATH但改完要重启终端才生效。我一般推荐第一种因为改 prefix 是一次性的加 PATH 每次换终端都可能忘。还有一个隐蔽的坑如果你之前用管理员权限装过全局包后来又用普通权限装两个 prefix 可能不一样导致同一个工具装了两份敲命令时执行的是旧的那份。排查方法是where 命令名Windows或which 命令名macOS/Linux看实际执行的是哪个路径下的文件。3.3 PowerShell 脚本执行策略的处理Windows 上跑 npm 相关命令时最常见的报错就是那句无法加载文件 npm.ps1因为在此系统上禁止运行脚本。这不是 npm 坏了是 PowerShell 默认的执行策略太严格不允许运行任何脚本文件。解决办法是改执行策略。以管理员身份打开 PowerShell运行Set-ExecutionPolicy RemoteSigned然后确认。RemoteSigned 的含义是本地写的脚本可以跑从网络下载的脚本需要签名。这个级别对开发环境来说够用也比 Unrestricted 安全。改完之后如果还是报错检查一下是不是在 VSCode 的内置终端里跑。VSCode 终端有时候会继承一个不同的执行策略上下文重启 VSCode 或者手动在终端里再设一次通常能解决。另外如果你用的是公司电脑执行策略可能被组策略锁死这种情况下Set-ExecutionPolicy会提示被覆盖需要联系 IT 处理自己改不了。注意不要为了图省事直接把执行策略设成 Bypass 或者 Unrestricted 全局生效尤其是在共用机器上。RemoteSigned 是开发场景下比较稳妥的选择。3.4 YAML 配置文件的组织结构openrig 的 YAML 配置建议按全局默认 工具命名空间 项目覆盖三层来组织。全局默认放超时、重试、日志级别这类工具命名空间放 Claude Code 和 Codex 各自的模型、端点、鉴权方式项目覆盖放具体项目对上下文长度、工作目录的特殊要求。version: 1 defaults: timeout: 120 retry: 3 log_level: info tools: claude_code: model: claude-sonnet context_window: 200000 config_dir: ~/.claude codex: model: gpt-5.6-sol endpoint: /responses config_dir: ~/.codex projects: my-refactor: tool: claude_code context_window: 1000000 workdir: ./src my-api: tool: codex endpoint: /responses workdir: ./api这个结构的好处是当你切换项目时只需要在projects下面选对应的条目执行层会自动把工具配置和项目覆盖合并。context_window在项目级别覆盖了工具级别的值这就是 YAML 合并的典型应用。注意version字段加版本号是为了将来配置格式升级时能做兼容判断这个习惯建议养成。4. 实操过程与核心环节实现4.1 从零搭建一套可用的 openrig 环境假设你现在是一台干净的 Windows 机器Node 已经装好我们要从零把 Claude Code 和 Codex 都跑起来并用 openrig 的 YAML 统一管理。下面是我实际走通的流程。第一步确认 npm 全局路径并修正。运行npm config get prefix如果输出的是C:\Program Files\nodejs这个路径通常需要管理员权限才能写入普通用户装全局包会失败。改成用户目录下的路径npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm改完关掉终端重开再npm config get prefix确认。然后确认这个路径在 PATH 里没有的话手动加。第二步处理 PowerShell 执行策略。管理员 PowerShell 里跑Set-ExecutionPolicy RemoteSigned确认。这一步做完npm.ps1的报错应该就消失了。第三步安装两个工具。Claude Code 和 Codex 的安装命令以官方当前发布为准通常是 npm 全局安装的形式npm install -g anthropic-ai/claude-code npm install -g openai/codex装完用claude --version和codex --version验证。如果提示命令找不到回到第一步检查 PATH。第四步写 openrig 的 YAML 配置。按 3.4 节的结构先写 defaults 和 tools 两块projects 先留空。把配置文件放在项目根目录命名openrig.yaml。第五步跑一次执行层命令让配置生效。具体命令取决于你用的 openrig 实现版本核心动作是读取 YAML、按命名空间写入各工具的配置目录、设置环境变量。跑完之后分别启动 Claude Code 和 Codex确认能正常连上各自的端点。4.2 模型端点配置的参数计算Codex 的端点配置里有个容易出问题的地方模型名和端点路径必须匹配。热词里出现的the gpt-5.6-sol model is not supported when using codex with a...这个报错根因就是模型名和端点不匹配。Codex 走/responses端点时对模型名有特定要求你写了一个该端点不支持的模型名就会报这个错。排查思路是先确认你用的端点是什么再确认这个端点支持哪些模型名。这两个信息通常在工具的官方文档或者配置示例里。不要凭记忆写模型名模型迭代很快上个月能用的名字这个月可能就变了。参数计算方面max_tokens和context_window的关系要理清。context_window是模型能接受的总上下文长度max_tokens是单次生成的最大输出长度。两者不是一回事。如果你把max_tokens设得接近context_window留给输入的空间就很小了长对话会很快触顶。我的经验值是max_tokens设在context_window的 10% 到 25% 之间具体看任务类型。重构类任务输入长输出短可以设低一点生成类任务反过来。4.3 多项目切换的配置合并逻辑openrig 在项目切换时做的合并顺序是 defaults → tools → projects后面的覆盖前面的。这个顺序很重要因为项目级的配置优先级最高工具级次之全局默认最低。合并的时候有个细节映射类型是深度合并还是浅合并。深度合并会把嵌套的键也逐层合并浅合并只替换顶层键。openrig 这类工具通常用深度合并因为这样项目级只需要写要覆盖的那几个键不用把整个工具配置重写一遍。# tools 里 codex 的配置 codex: model: gpt-5.6-sol endpoint: /responses timeout: 120 # projects 里某个项目只覆盖 timeout my-api: tool: codex timeout: 300深度合并之后这个项目实际生效的 codex 配置是 model 和 endpoint 沿用工具级timeout 用项目级的 300。如果是浅合并整个 codex 块会被替换model 和 endpoint 就丢了。所以你在写项目覆盖的时候要确认工具用的是哪种合并策略不确定的话就把需要的键都写全虽然啰嗦但不会出错。4.4 配置生效的验证方法配置写完不等于生效。我习惯用三步验证第一步让执行层输出合并后的最终配置很多工具支持--dry-run或者--print-config这类参数能看到实际生效的值第二步启动工具后用工具自己的命令查看当前配置比如 Claude Code 有查看当前模型和上下文的命令第三步跑一个最小任务比如让它读一个文件然后回答一个问题确认端点和鉴权都通。这三步里第一步最关键。很多人跳过第一步直接跑任务出错了再回头猜哪里配错了效率很低。能看到合并后的最终配置问题基本一眼就能定位。5. 常见问题与排查技巧实录5.1 npm 相关报错速查npm 的报错信息有时候很误导人同一个现象可能有好几种根因。我整理了一张速查表按报错现象反查原因。报错现象可能原因排查动作npm.ps1 禁止运行脚本PowerShell 执行策略Set-ExecutionPolicy RemoteSigned全局装完命令找不到prefix 不在 PATHnpm config get prefix对比 PATHERESOLVE overriding peer dependency依赖版本冲突看警告里的包名考虑--legacy-peer-deps安装卡住不动源速度慢换国内镜像源装了两份同名工具多 prefix 并存where 命令名看实际路径ERESOLVE这个警告特别常见它本身不一定是错误只是提示某个 peer dependency 被覆盖了。如果安装最终成功了这个警告可以忽略。但如果安装失败就要认真看是哪个包的版本要求冲突了。--legacy-peer-deps能绕过检查但这是权宜之计长期看还是要理顺依赖版本。5.2 端点与模型不匹配的排查前面提到的gpt-5.6-sol model is not supported这类报错排查顺序是先看端点路径对不对再看模型名对不对最后看两者组合是否被支持。这三个是独立的检查点不要混在一起猜。我遇到过一次端点路径写对了模型名也写对了但还是报不支持。最后发现是配置文件里有两处定义了模型名一处是工具级一处是项目级项目级的那个是旧的合并之后覆盖了工具级的新值。这种问题就是配置分散导致的所以我在 3.4 节强调配置要有清晰的组织结构别到处散落。5.3 鉴权失败的几种表现鉴权问题在 Claude Code 和 Codex 上表现不一样。Claude Code 如果订阅鉴权出问题可能提示组织禁用了订阅访问这类信息这时候要检查的是账号状态和订阅配置不是本地环境。Codex 的鉴权失败通常表现为请求被拒或者返回鉴权错误码要检查的是 API key 或者登录状态。这两类问题的排查方向完全不同所以第一步是先判断是鉴权问题还是配置问题。判断方法很简单如果报错信息里出现了账号、订阅、组织、权限这类词往鉴权方向查如果出现的是模型名、端点、格式这类词往配置方向查。5.4 本地模型接入的注意事项热词里有claude code 调用 lmstudio 的本地模型这个场景值得单独说。本地模型接入的核心是把端点指向本地服务比如http://localhost:1234这类地址。但要注意几点本地模型的上下文长度通常比云端模型小很多配置里的context_window要相应调小不然工具会按大窗口去组织请求本地服务处理不了本地模型的响应格式可能和云端不完全一致如果工具对响应格式有严格校验可能会解析失败本地服务的并发能力有限retry和timeout参数要调得保守一些。我实测下来本地模型适合做轻量的代码补全和问答重度的长上下文重构还是得用云端模型。把本地模型配成 fallback云端不可用时顶上这个用法比较实际。5.5 配置回滚与版本管理openrig 的 YAML 配置一定要进版本控制。我见过有人配置改坏了又没有备份只能从头重写。YAML 文件本身是纯文本git 管理起来很方便每次改动都有记录出问题能 diff 出改了什么。建议的做法是主配置进 git本地个性化覆盖用一个单独的openrig.local.yaml这个文件加进.gitignore不提交。执行层读取时先读主配置再读本地覆盖这样团队共享的部分和个人的部分分开既保证一致性又保留灵活性。提示改配置之前先 commit 一次当前状态改完跑验证通过了再 commit。这样任何一次改动出问题都能一键回到上一个可用状态。6. 我踩过的坑和几条实用建议配置管理这件事工具本身只解决一半问题另一半靠使用习惯。我折腾这套东西最大的体会是不要追求一次配到完美先跑通最小可用版本再逐步加东西。一开始就想把所有工具、所有项目、所有参数都配齐结果往往是配置写了一堆一个都没验证通过最后不知道错在哪。另一个体会是关于报错信息的。AI 编程工具的报错有时候很笼统比如只说请求失败不告诉你具体哪一步失败。这时候不要盯着报错本身看要回到配置的合并结果上确认实际生效的值是什么。大部分问题都是配置合并后和预期不一致导致的而不是工具本身有 bug。最后分享一个我常用的小技巧给每个工具配一个健康检查命令就是一条最简单的、能验证端到端通路的命令。每次改完配置先跑健康检查通过了再干正事。这条命令可以是一条简单的问答也可以是一个固定的测试任务。有了它配置改动的影响范围就控制住了不会改一处崩一片。
