openrig：用YAML统一管理Claude Code与Codex的AI编程环境配置

1. openrig 到底想解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 “rig” 在英文里常指设备支架、矿机架或者实验台。但结合 Claude Code、Codex、YAML、Node.js 这组关键词来看，它显然是一个围绕 AI 编程助手工作流的配置编排工具。我个人的理解是：openrig 试图把 Claude Code、Codex 这类命令行 AI 编程工具的安装、配置、模型接入、代理切换、项目级参数管理，统一收敛到一套可版本控制的 YAML 配置里，再用 Node.js 生态把它跑起来。

这件事为什么值得做？因为现在用 AI 编程助手的人越来越多，但大多数人的配置方式是“散装”的：Claude Code 装一遍、Codex 装一遍、VS Code 插件配一遍、终端环境变量再配一遍。换台机器、换个项目、换家公司网络环境，全部重来。更麻烦的是，很多人同时用多个模型供应商，今天用这个，明天切那个，配置文件改来改去，最后自己都记不清哪个项目用的是哪套参数。openrig 的价值就在于把这些零散的配置动作抽象成声明式的 YAML 文件，让“换环境”变成“换一份配置”。

它适合谁？第一类是从零开始搭建 AI 编程环境的开发者，尤其是刚接触 Claude Code 和 Codex 的人，跟着一份 openrig 配置走，能少踩很多安装和路径的坑。第二类是多项目、多模型切换的重度用户，比如白天在公司用一套模型，晚上在家用另一套，openrig 可以把差异隔离在配置文件里。第三类是想把团队开发环境标准化的技术负责人，把 openrig 配置提交到仓库，新人拉下来就能跑，不用再写长篇的“环境搭建文档”。

需要提前说明的是，openrig 目前并不是一个像 VS Code 那样有庞大官方文档的成熟产品，它更像是一个围绕 AI 编程工具链的配置约定和脚本集合。所以这篇文章不会假装它有一个完美的官方手册，而是基于这类工具常见的实现方式，结合 Claude Code、Codex、Node.js、YAML 的实际使用经验，把一套可落地的方案讲清楚。你完全可以把下面的内容当作“如果我要自己搭一个 openrig，我会怎么做”的完整记录。

2. 核心设计思路与方案选型

2.1 为什么用 YAML 做配置层而不是 JSON 或 TOML

YAML 在这类工具里几乎是默认选择，原因很实际。Claude Code 和 Codex 本身就有不少配置文件是 YAML 或类 YAML 格式，比如模型参数、项目上下文、工具权限列表。用 YAML 做 openrig 的配置层，能和这些工具的生态保持一致，减少格式转换的心智负担。

JSON 的问题在于不能写注释。AI 编程工具的配置里经常需要标注“这个 key 是哪个供应商的”“这个参数为什么设成 0.2”，JSON 一旦要注释就得靠额外字段，很别扭。TOML 虽然也能注释，但嵌套结构写起来比 YAML 啰嗦，尤其是当你要描述“多个模型供应商 + 每个供应商多个端点 + 每个端点多个参数”这种三层结构时，YAML 的缩进表达更直观。

不过 YAML 也有坑。最大的坑是缩进必须用空格，不能用 Tab。我见过太多人从网页复制配置，粘贴进去发现报错，排查半天结果是混入了 Tab。另一个坑是 YAML 对特殊字符敏感，比如冒号后面必须跟空格，字符串里如果有{{ }}这种模板符号，最好用引号包起来。openrig 如果要做配置校验，第一件事就应该是检查 YAML 语法，而不是等到运行时才报错。

提示：写 openrig 配置时，建议在编辑器里开启“显示空白字符”，Tab 和空格一眼就能看出来。VS Code 里搜renderWhitespace设为all即可。

2.2 Node.js 在 openrig 里扮演什么角色

Node.js 在这套方案里不是可选项，而是粘合剂。Claude Code 和 Codex 的 CLI 工具很多都是 Node.js 写的，或者至少通过 npm 分发。openrig 要用 Node.js 做几件事：读取 YAML 配置、校验配置结构、根据配置生成各个工具需要的实际配置文件、调用 CLI 命令完成安装或切换。

为什么不用 Python 或 Shell？Shell 做简单切换可以，但一旦涉及 YAML 解析、JSON 合并、路径处理，Shell 脚本会变得非常难维护。Python 当然也能做，但 AI 编程工具链的生态明显更偏 Node.js，很多包和示例都是 npm 的。用 Node.js 可以少装一套运行时，而且和 Claude Code、Codex 的安装方式一致，用户只需要一个 Node.js 环境就能跑通全部流程。

Node.js 版本选择上，我建议用 LTS 版本。热词里有人遇到 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这种报错，说明版本号写错了或者源里还没有这个版本。稳妥的做法是去 Node.js 官网下载 LTS 安装包，或者用 nvm 管理版本。openrig 的配置文件里可以声明engines.node字段，比如>=18.0.0，这样运行时能给出明确提示，而不是抛出一堆看不懂的语法错误。

2.3 多工具共存的目录结构设计

Claude Code 和 Codex 默认会把配置放在用户主目录下，比如~/.claude、~/.codex这类路径。如果 openrig 直接改这些目录，风险是污染全局环境，而且不同项目之间会互相干扰。更合理的做法是采用“项目级配置 + 全局软链接”或者“环境变量注入”的方式。

我倾向于项目级配置优先。openrig 在项目根目录放一个.openrig/文件夹，里面包含openrig.yaml主配置、profiles/子配置、generated/生成结果。运行时通过环境变量或者命令行参数，把 Claude Code、Codex 的配置路径指向.openrig/generated/下的文件。这样每个项目可以有独立的模型选择、独立的 API 端点、独立的权限设置，互不影响。

全局配置则放在~/.openrig/下，作为默认值。项目级配置可以继承全局配置，也可以完全覆盖。这种“全局默认 + 项目覆盖”的模式，和 Git 的配置逻辑很像，用户理解成本低。具体实现时，Node.js 脚本先读全局 YAML，再读项目 YAML，用深合并的方式生成最终配置。深合并的规则要明确：对象递归合并，数组直接替换，null 表示删除该键。

2.4 模型供应商切换的抽象方式

热词里出现了 “cc switch local proxy failed while handling codex endpoint /responses” 和 “使用 cc switch 接入 deepseek v4, qwen, glm 等模型”，说明很多人有切换模型供应商的强需求。openrig 如果把供应商切换做成配置项，就能避免手动改环境变量。

我的设计思路是：在 YAML 里定义providers列表，每个 provider 有name、baseUrl、apiKeyEnv、models等字段。然后定义profiles，每个 profile 指定当前使用哪个 provider、哪个 model、哪些工具参数。切换时只需要改 profile 名称，或者用命令行参数--profile work临时指定。

这里有个关键点：API Key 绝对不能明文写在 YAML 里。正确做法是 YAML 里只写环境变量名，比如apiKeyEnv: OPENRIG_WORK_API_KEY，实际值通过系统环境变量或.env文件注入。.env文件要加入.gitignore，避免提交到仓库。openrig 在生成最终配置时，从环境变量读取真实值，再写入工具需要的配置文件。这样既方便切换，又不会泄露密钥。

3. 核心细节解析与实操要点

3.1 openrig.yaml 的字段设计

一份可用的 openrig 配置，至少需要覆盖版本声明、运行时要求、供应商定义、工具配置、项目覆盖这几个部分。下面是我实际用过的一个结构示例，你可以直接拿去改：

version: 1 runtime: node: ">=18.0.0" packageManager: npm providers: - name: default baseUrl: "https://api.example.com/v1" apiKeyEnv: OPENRIG_DEFAULT_KEY models: - name: coding-model contextWindow: 128000 maxOutput: 8192 - name: backup baseUrl: "https://api.backup.com/v1" apiKeyEnv: OPENRIG_BACKUP_KEY models: - name: fast-model contextWindow: 32000 maxOutput: 4096 tools: claude-code: enabled: true configPath: ".openrig/generated/claude-code.json" defaultProfile: work codex: enabled: true configPath: ".openrig/generated/codex.yaml" defaultProfile: work profiles: work: provider: default model: coding-model temperature: 0.2 permissions: allowShell: true allowFileWrite: true personal: provider: backup model: fast-model temperature: 0.7 permissions: allowShell: false allowFileWrite: true

这个结构里，version用于未来做配置迁移，runtime用于版本检查，providers和profiles分离是为了让“连接信息”和“使用场景”解耦。tools部分控制每个工具是否启用以及生成路径。实际项目中，你还可以加env字段做全局环境变量注入，加hooks字段在切换前后执行脚本。

字段命名上，我建议用 kebab-case 而不是 camelCase，因为 YAML 社区和很多 CLI 工具更习惯 kebab-case。比如apiKeyEnv写成api-key-env也可以，但要注意 Node.js 读取后的映射逻辑。关键是团队内部统一，不要一半 camelCase 一半 snake_case。

3.2 配置校验与错误提示

YAML 写错是常态，所以 openrig 必须有校验层。校验分三步：语法校验、结构校验、语义校验。语法校验用yaml包解析，捕获缩进、冒号、引号问题。结构校验用zod或ajv定义 schema，检查必填字段、类型、枚举值。语义校验检查引用的 provider 是否存在、model 是否在 provider 的 models 列表里、环境变量是否已设置。

错误提示要具体到行号和字段路径。比如不要只说“配置无效”，而要说“profiles.work.provider 引用了不存在的 provider: default2，请检查 providers 列表”。Node.js 里可以用yaml包的parseDocument方法拿到 AST，再结合doc.errors输出带行号的错误。这一步做得好，用户排查配置问题的时间能减少一大半。

注意：环境变量检查不要在校验阶段直接报错退出，因为有些场景下用户可能先校验配置结构，稍后再设置环境变量。更好的做法是分两级：openrig validate只做结构和语法校验，openrig apply才检查环境变量并生成配置。

3.3 生成 Claude Code 和 Codex 的实际配置

Claude Code 和 Codex 的配置格式不完全一样，openrig 需要做适配层。以 Claude Code 为例，它可能接受 JSON 格式的配置文件，包含模型端点、API Key、权限列表。Codex 可能接受 YAML 或 TOML。openrig 的生成器要根据tools里的configPath和工具类型，把统一的 profile 转换成各自需要的格式。

转换过程中有几个细节容易出错。第一是路径问题：生成的配置里如果包含相对路径，要相对于配置文件所在目录解析，而不是相对于当前工作目录。第二是权限字段的映射：Claude Code 的allowShell和 Codex 的sandbox可能不是一一对应，需要做映射表。第三是模型名称：不同供应商对同一个模型的命名可能不同，openrig 的 provider 定义里最好支持aliases字段。

我实际用的时候，会在.openrig/generated/下同时生成多个文件，比如claude-code.json、codex.yaml、env.sh。env.sh用于在 shell 里 source，快速导出环境变量。生成文件头部加一行注释“此文件由 openrig 自动生成，请勿手动修改”，避免用户改完又被覆盖。

3.4 与 VS Code 的集成方式

热词里 “vscode配置claude code” 和 “claude code for vs code” 出现频率很高，说明很多人是在 VS Code 里用这些工具。openrig 和 VS Code 的集成有两种方式：一种是通过 VS Code 的 settings.json 注入配置，另一种是通过终端集成，让 VS Code 的集成终端自动加载 openrig 生成的环境变量。

第一种方式适合插件类工具，比如 Claude Code 的 VS Code 插件。openrig 可以生成一个.vscode/settings.json片段，或者直接修改工作区的 settings。但直接修改用户文件有风险，更好的做法是生成.vscode/openrig-settings.json，然后在文档里告诉用户怎么合并。第二种方式更通用：在.vscode/settings.json里配置terminal.integrated.env.linux或对应平台的字段，把 openrig 的环境变量注入进去。这样在 VS Code 终端里运行 Claude Code 或 Codex，自动就是当前 profile 的配置。

如果你用的是远程开发或者容器开发，openrig 的配置可以放在容器镜像的构建阶段，通过postCreateCommand执行openrig apply。这样每个开发者打开容器，环境就是一致的。

4. 完整实操流程与关键环节

4.1 环境准备：Node.js 与包管理器

第一步是确认 Node.js 环境。打开终端，运行node -v和npm -v。如果没装，去 Node.js 官网下载 LTS 版本。Windows 用户建议用官方安装包，macOS 用户可以用 Homebrew 或官方包，Linux 用户建议用 nvm 管理。nvm 的好处是可以在不同项目间切换 Node.js 版本，openrig 的runtime.node字段就能派上用场。

安装完 Node.js 后，建议设置 npm 的镜像源，尤其是网络环境不稳定的情况。但这里不展开具体源地址，你根据自己所在网络环境选择可用的源即可。设置命令是npm config set registry <你的源地址>。设置完用npm config get registry确认。

然后安装 openrig。如果 openrig 已经发布到 npm，直接npm install -g openrig。如果是本地开发版本，进入项目目录运行npm link。安装完运行openrig --version，能输出版本号就说明安装成功。如果报 “command not found”，检查 npm 全局 bin 目录是否在 PATH 里。npm bin -g可以查看全局 bin 路径。

4.2 初始化项目配置

进入你的项目根目录，运行openrig init。这个命令会做几件事：创建.openrig/目录，生成openrig.yaml模板，创建.openrig/profiles/和.openrig/generated/子目录，在.gitignore里追加.openrig/generated/和.env。

生成的openrig.yaml模板里，provider 的baseUrl和apiKeyEnv是占位符，需要你手动填写。如果你用的是公司内部模型服务，找管理员要 baseUrl 和 API Key 的获取方式。如果用的是公开模型服务，去对应平台的控制台创建 API Key。拿到 Key 后，不要直接写进 YAML，而是写进.env文件：

OPENRIG_DEFAULT_KEY=你的实际密钥 OPENRIG_BACKUP_KEY=另一个密钥

然后在openrig.yaml里保持apiKeyEnv: OPENRIG_DEFAULT_KEY不变。openrig 在 apply 时会自动读取.env文件。这里有个细节：.env文件的加载顺序应该是“系统环境变量优先，.env文件兜底”。也就是说，如果系统里已经设置了OPENRIG_DEFAULT_KEY，就用系统的，否则用.env里的。这样在 CI 环境里可以通过系统环境变量注入，本地开发用.env，两边都不冲突。

4.3 配置校验与试运行

写完配置后，运行openrig validate。这个命令只做校验，不生成文件。如果报错，根据提示逐项修复。常见的校验错误包括：YAML 缩进错误、provider 名称重复、profile 引用了不存在的 provider、model 不在 provider 的 models 列表里、runtime.node版本不满足当前 Node.js 版本。

校验通过后，运行openrig plan。这个命令会输出“将要生成哪些文件、每个文件的内容摘要、将设置哪些环境变量”，但不实际写入。这一步很像 Terraform 的 plan，让你在真正改动之前确认一遍。我强烈建议每次改完配置都先 plan 再 apply，尤其是多人协作的项目，避免误覆盖别人的配置。

确认无误后，运行openrig apply。这个命令会生成配置文件、写入.openrig/generated/、输出环境变量导出脚本。如果tools.claude-code.enabled为 true，还会检查 Claude Code 是否已安装，未安装则提示安装命令。Codex 同理。

4.4 在终端中激活配置

apply 完成后，需要让当前终端会话加载 openrig 的环境变量。运行eval "$(openrig env)"，这个命令会输出 export 语句，eval 后当前 shell 就拥有了正确的环境变量。如果你用的是 fish shell，运行openrig env --shell fish | source。Windows PowerShell 用户运行openrig env --shell powershell | Invoke-Expression。

为了避免每次开终端都手动执行，可以把这行命令加到 shell 的启动文件里，比如~/.bashrc或~/.zshrc。但要注意，如果项目目录经常切换，全局加载可能会导致配置混乱。更好的做法是写一个 shell 函数，进入项目目录时自动检测.openrig/并加载：

openrig_auto_load() { if [ -f ".openrig/openrig.yaml" ]; then eval "$(openrig env)" fi } cd() { builtin cd "$@" && openrig_auto_load }

这样每次 cd 到有 openrig 配置的目录，自动切换环境。离开目录后，环境变量还在，但下次 cd 到别的项目会覆盖。如果想彻底清理，运行openrig env --unset输出 unset 语句。

4.5 切换 profile 的几种方式

日常使用中，切换 profile 是最频繁的操作。openrig 支持三种切换方式。第一种是修改openrig.yaml里的defaultProfile，然后重新 apply。这种方式适合长期切换，比如从“工作模式”切到“个人模式”。第二种是命令行参数：openrig apply --profile personal，临时覆盖默认 profile，不修改配置文件。第三种是环境变量：OPENRIG_PROFILE=personal openrig apply，适合在脚本或 CI 里使用。

切换后，Claude Code 和 Codex 的配置会重新生成。如果工具正在运行，需要重启工具才能加载新配置。有些工具支持热重载，但大多数 CLI 工具还是需要重启。我一般会在切换后运行openrig status，确认当前生效的 provider、model、profile 名称，避免切了没生效。

4.6 与 Claude Code 和 Codex 的联调

配置生成后，实际运行 Claude Code 或 Codex 验证。以 Claude Code 为例，运行claude进入交互界面，然后问一个简单问题，比如“当前目录下有哪些文件”。如果模型能正常响应，说明 API 端点和 Key 配置正确。如果报 401，检查 API Key 是否过期或环境变量是否加载。如果报 404，检查 baseUrl 是否缺少/v1后缀或者路径拼写错误。

Codex 的验证类似。运行codex后，输入一个需要读取文件的任务，观察是否能正常调用工具。热词里 “codex无法加载组织设置” 可能和权限配置有关，openrig 的permissions字段可以控制是否允许 shell 执行和文件写入。如果 Codex 报权限错误，检查 profile 里的allowShell和allowFileWrite是否设置正确。

联调阶段最容易忽略的是网络超时。有些模型服务在特定网络环境下响应很慢，openrig 可以在 provider 里加timeout字段，生成配置时写入工具的 timeout 设置。默认值建议 30 秒，如果模型推理时间长，可以调到 120 秒。

5. 常见问题与排查技巧实录

5.1 安装类问题速查

这张表里的问题，我几乎每个都遇到过。尤其是 YAML 缩进问题，看起来简单，但在复制粘贴场景下极其常见。我的习惯是配置写完后先跑openrig validate，不要等到 apply 才检查。

5.2 配置类问题排查思路

配置类问题最典型的是“改了没生效”。排查顺序应该是：先确认改的是哪个文件，再确认 openrig 读的是哪个文件，最后确认工具读的是哪个文件。openrig 支持--config参数指定配置文件路径，如果你在项目子目录里运行，可能读的是全局配置而不是项目配置。运行openrig status --verbose可以看到完整的配置加载链路。

另一个常见问题是环境变量没加载。openrig env输出的变量，需要 eval 或 source 才生效。如果你直接运行openrig env看到输出，但工具里读不到，说明没有 eval。可以在工具里打印process.env.OPENRIG_PROFILE确认。如果用的是 VS Code 集成终端，检查terminal.integrated.env配置是否覆盖了 openrig 的设置。

API Key 泄露也是配置类问题里需要警惕的。如果你不小心把.env提交到了仓库，立即撤销提交并更换 Key。openrig 的init命令会自动把.env加入.gitignore，但如果你手动创建了.env或者改了.gitignore，需要自己检查。运行git check-ignore .env可以确认是否被忽略。

5.3 模型接入类问题实录

热词里 “claude code 调用 lmstudio 的本地模型” 和 “codex接入deepseek” 说明很多人尝试接入非官方模型。这类接入最常见的问题是 API 格式不兼容。Claude Code 和 Codex 可能期望特定的请求格式，而本地模型或第三方服务的返回格式不同。openrig 可以在 provider 里加apiFormat字段，生成配置时选择对应的适配器。

如果遇到 “cc switch local proxy failed while handling codex endpoint /responses” 这类错误，通常是代理层在转发请求时路径或请求体不匹配。排查时先用 curl 直接请求模型端点，确认基础连通性。然后再通过 openrig 生成的配置请求，对比两者差异。常见差异包括：请求头缺少Content-Type、路径多了或少了/v1、请求体里的model字段名称不对。

本地模型还有一个坑是上下文窗口。LM Studio 加载的模型可能只支持 8K 或 32K 上下文，但 Claude Code 默认可能按 128K 发送请求，导致截断或报错。openrig 的 provider 里定义contextWindow就是为了生成配置时限制工具的最大上下文。如果工具不支持这个配置，可以在 openrig 里做请求预处理，截断过长的上下文。

5.4 权限与组织策略类问题

“your organization has disabled claude subscription access for claude code” 这类提示，说明账号所属组织限制了访问。这不是 openrig 能解决的问题，但 openrig 可以在配置里支持多个 provider，当主 provider 不可用时快速切换到备用 provider。我的做法是在 profile 里定义fallback字段，指定备用 provider 和 model。openrig 在 apply 时可以检测主 provider 的连通性，不通则自动生成备用配置。

“codex无法加载组织设置” 可能和 Codex 的组织级配置有关。Codex 可能从某个远程端点拉取组织策略，如果网络不通或认证失败，就会报这个错。排查时先确认 Codex 本身的登录状态，再确认 openrig 生成的配置是否覆盖了组织设置相关的字段。有些工具的组织设置是只读的，openrig 不应该尝试修改，而是通过环境变量或命令行参数传递。

5.5 跨平台差异与注意事项

Windows、macOS、Linux 在路径分隔符、环境变量语法、shell 类型上都有差异。openrig 生成配置时要处理这些差异。比如 Windows 用\而 Unix 用/，Node.js 的path模块可以自动处理。环境变量导出脚本要根据 shell 类型生成不同语法，bash 用export，fish 用set -x，PowerShell 用$env:。

Windows 上还有一个特殊问题是长路径限制。如果项目路径很深，生成的配置文件路径可能超过 260 字符。解决办法是开启 Windows 的长路径支持，或者把 openrig 的生成目录放在较浅的路径下。另外 Windows 的换行符是\r\n，YAML 解析器一般能处理，但如果你用脚本生成 YAML，要注意换行符统一。

macOS 的默认 shell 从 bash 换成了 zsh，启动文件也变成了~/.zshrc。如果你按旧教程改~/.bashrc，可能不生效。运行echo $SHELL确认当前 shell，再改对应的启动文件。

6. 进阶用法与个人经验

6.1 把 openrig 配置纳入版本控制

.openrig/openrig.yaml和.openrig/profiles/应该提交到仓库，.openrig/generated/和.env不应该提交。这样团队成员拉下代码后，只需要创建自己的.env文件，运行openrig apply，就能得到一致的配置。如果团队用不同的模型供应商，可以在profiles/下每人一个 profile 文件，通过OPENRIG_PROFILE环境变量选择。

提交前建议跑一次openrig validate --strict，严格模式会检查所有环境变量是否已定义、所有引用的 provider 是否存在、所有路径是否可写。CI 里也可以加这一步，防止有人提交了错误的配置。

6.2 用 openrig 管理多项目环境

如果你同时维护多个项目，每个项目有自己的 openrig 配置，切换项目时环境变量会互相覆盖。我的做法是在每个项目的.openrig/openrig.yaml里设置不同的envPrefix，比如项目 A 用PROJA_，项目 B 用PROJB_。这样环境变量不会冲突，工具配置也各自独立。

另一个技巧是用 direnv 配合 openrig。direnv 可以在进入目录时自动执行脚本，把eval "$(openrig env)"写进.envrc，离开目录时自动卸载。这样完全不用手动切换，体验很流畅。direnv 支持 bash、zsh、fish，安装配置也不复杂。

6.3 性能优化与缓存

openrig 每次 apply 都要读 YAML、校验、生成文件，如果配置很大，可能会慢。优化方式是对校验结果做缓存，YAML 文件的 mtime 没变就跳过重新校验。生成文件也可以做增量，只重新生成内容变化的文件。Node.js 里可以用fs.stat拿 mtime，用crypto.createHash对配置内容做哈希，哈希没变就跳过。

如果 openrig 需要调用外部命令检查工具版本，这些调用可以并行化。Node.js 的child_process.exec配合Promise.all可以同时检查多个工具，减少等待时间。但要注意并发数不要太高，避免系统资源耗尽。

6.4 我踩过的几个坑

第一个坑是 YAML 里的布尔值。YAML 1.1 里yes、no、on、off都会被解析成布尔值，但 YAML 1.2 里只有true、false是布尔值。如果你写enabled: yes，不同解析器行为可能不一致。统一用true和false最稳妥。

第二个坑是环境变量里的特殊字符。API Key 里可能包含$、!、&等字符，在 shell 里直接 export 会被解释。openrig 生成 env 脚本时，要对值做转义，或者用单引号包裹。更安全的做法是生成.env文件而不是 export 语句，让工具自己读取。

第三个坑是路径里的空格。如果项目路径包含空格，生成的配置里路径字段要用引号包裹，否则工具解析时会截断。Node.js 的JSON.stringify会自动处理引号，但如果你手动拼接字符串，很容易漏掉。

第四个坑是并发 apply。如果两个终端同时运行openrig apply，可能同时写同一个生成文件，导致内容错乱。解决办法是加文件锁，Node.js 可以用proper-lockfile包。或者约定 apply 是原子操作，先写临时文件再重命名。

6.5 后续可以扩展的方向

openrig 目前聚焦在配置生成和环境切换，后续可以扩展的方向不少。比如加一个openrig doctor命令，自动诊断常见问题：Node.js 版本、网络连通性、API Key 有效性、工具版本兼容性。再比如加openrig benchmark，对不同的 provider 和 model 做延迟和吞吐测试，帮用户选择最优配置。

还可以做配置模板市场，用户分享自己的 openrig 配置，其他人一键导入。或者和 CI/CD 集成，在流水线里用 openrig 生成测试环境的 AI 工具配置，跑自动化代码审查。这些方向都建立在“配置即代码”的理念上，和 openrig 的核心价值一致。

我个人在实际操作中的体会是，openrig 这类工具的价值不在于功能多复杂，而在于把重复的配置动作标准化。一旦团队里每个人都用同一套配置逻辑，沟通成本会大幅下降。新人不再问“你的 API Key 怎么配的”，而是直接看openrig.yaml。模型切换不再靠记忆，而是改一个 profile 名称。这种确定性的提升，比省下几分钟配置时间重要得多。