1. openrig 到底是个什么东西
第一次看到 openrig 这个名字，我下意识以为是某个硬件测试架或者开源机械臂项目，毕竟 rig 这个词在工程领域通常指“装配、调试台架”。但结合热搜词里那一串 Claude Code、Codex、YAML、Node.js 来看，这明显是一个跟 AI 编程助手配置管理相关的工具。简单说，openrig 要解决的核心问题是：当你同时使用 Claude Code、Codex 这类命令行 AI 编程助手时，如何用一份统一的 YAML 配置文件来管理它们的模型接入、代理设置、环境变量和启动参数，而不是每次切换工具都要手动改一堆环境变量或者翻配置文件。
这个痛点我太熟悉了。早几个月我同时用 Claude Code 写日常业务代码，用 Codex 处理一些需要长上下文推理的任务，结果就是两套配置各管各的，API key 散落在不同的 shell 配置文件里，模型名称写错一个字母就要排查半天。更麻烦的是，当你想把 Claude Code 接到本地 LM Studio 跑的模型上，或者让 Codex 走 DeepSeek 的接口时，每个工具的环境变量命名规则还不一样，Claude Code 用ANTHROPIC_BASE_URL，Codex 用OPENAI_BASE_URL，记混了就是各种 401 或者 model not supported 报错。
openrig 的思路就是把这些碎片化的配置收拢到一个 YAML 文件里，通过一个统一的命令行入口来启动不同的 AI 编程助手。你可以在 YAML 里定义多个 profile，每个 profile 指定用哪个工具、接哪个模型、走哪个 endpoint、传哪些额外参数。想切换的时候不用改环境变量，直接openrig run claude或者openrig run codex就行。适合谁用？我觉得三类人最需要：一是同时用多个 AI 编程助手的开发者，二是需要频繁在本地模型和云端模型之间切换的人，三是团队里想把 AI 助手配置标准化、避免每个人环境不一致导致各种玄学问题的技术负责人。
2. 为什么需要 openrig 这层封装
2.1 多工具配置管理的真实困境
先说说不用 openrig 的时候，配置有多乱。Claude Code 的配置通常放在~/.claude/settings.json或者通过环境变量注入，Codex 的配置在~/.codex/config.yaml或者~/.config/codex/下面，两者格式不同、字段命名不同、优先级规则也不同。如果你还用了 cc switch 这类代理切换工具，那又多了一层配置。我试过在一台机器上同时维护三套配置，每次换模型都要确认哪个文件生效、哪个环境变量覆盖了哪个，排查一个连接失败的问题能花掉半小时。
更隐蔽的问题是环境变量的污染。比如你在.zshrc里设了OPENAI_API_KEY给 Codex 用，结果 Claude Code 某些版本也会去读这个变量，导致你以为在用 Anthropic 的模型，实际上请求发到了别的地方。这种问题不会报错，只会让你觉得“今天模型怎么变笨了”。openrig 通过隔离每个 profile 的环境变量作用域来解决这个问题，启动 Claude 的时候只注入 Claude 需要的变量，启动 Codex 的时候只注入 Codex 需要的，互不干扰。
2.2 YAML 作为配置格式的取舍
为什么选 YAML 而不是 JSON 或者 TOML？JSON 的问题是写注释不方便，而 AI 助手配置里经常需要标注“这个 key 是临时的”“这个 endpoint 只在公司内网可用”，注释很重要。TOML 虽然支持注释，但嵌套结构表达起来比较啰嗦，尤其是当你要定义多个 profile、每个 profile 下面又有 model、endpoint、env、args 多个层级时，YAML 的缩进结构更直观。当然 YAML 也有坑，比如缩进必须用空格不能用 Tab，字符串里的冒号要加引号，这些后面会细说。
openrig 的 YAML 结构我推测大概是这样的：顶层有一个profiles字典，每个 key 是 profile 名称，value 里包含tool（claude 或 codex）、model、base_url、api_key_env（指定从哪个环境变量读 key，避免明文写在文件里）、extra_env、args等字段。这样设计的好处是敏感信息不落盘，配置文件可以安全地提交到团队仓库里共享。
2.3 与直接改 shell 配置的对比
有人可能会说，我直接在.zshrc里写几个 alias 不就行了？比如alias claude-deepseek='ANTHROPIC_BASE_URL=xxx ANTHROPIC_API_KEY=xxx claude'。短期看确实能跑，但问题会随着配置增多而爆炸。第一，alias 里没法方便地传动态参数，比如今天想用 sonnet 明天想用 opus，你得写两个 alias 或者每次手动改。第二，alias 不支持条件逻辑，比如“如果本地 LM Studio 在运行就用本地模型，否则用云端”。第三，团队共享时 alias 散落在各人的 dotfiles 里，新人入职要手动抄一遍，抄错了就是各种诡异报错。
openrig 相当于把 alias 升级成了一个有结构的配置系统，支持继承、覆盖、默认值，还能做启动前的健康检查。比如你可以在 profile 里定义一个health_check字段，启动前先 curl 一下 endpoint 是否可达，不可达就自动 fallback 到备用模型。这种逻辑用 alias 是写不出来的。
3. 环境准备与 Node.js 安装避坑
3.1 Node.js 版本选择：为什么 20+ 是底线
openrig 本身大概率是个 Node.js 写的 CLI 工具，热搜词里出现了“node.js安装”“node.js下载”“ubuntu安装node.js 20+”“error installing 24.21.0: node.js v24.21.0 is not yet released”这些，说明版本问题是新手最容易卡住的地方。我的建议很明确：用 Node.js 20 LTS 或者 22 LTS，不要追最新的奇数版本。原因有两个：一是 LTS 版本有长期维护，npm 生态兼容性最好；二是很多 AI 编程助手工具链里的依赖（比如某些 native 模块）在最新版 Node 上还没预编译好，装的时候会触发 node-gyp 编译，然后因为缺少 Python 或 C++ 构建工具而失败。
那个“v24.21.0 is not yet released”的报错，通常是因为你用了 nvm 或者 n 这类版本管理器，但指定的版本号在镜像源里还不存在。解决办法很简单：先nvm ls-remote --lts看看有哪些 LTS 版本可用，然后nvm install 20或者nvm install 22。如果你在 Ubuntu 上直接用 apt 装，默认源里的 Node 版本可能很老（比如 12 或 14），需要先加 NodeSource 的源。
3.2 Ubuntu 下安装 Node.js 20+ 的实操步骤
在 Ubuntu 22.04 或 24.04 上，我习惯用 NodeSource 的脚本，比手动配 apt 源省事：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完之后验证一下：
node -v npm -v如果node -v输出的是 v20.x.x 就对了。这里有个坑：如果你之前用 apt 装过旧版 Node，NodeSource 脚本可能不会自动卸载旧版，导致node命令指向的还是老版本。这时候用which node看一下路径，如果是/usr/bin/node而不是/usr/local/bin/node，就手动sudo apt remove nodejs再重装。
注意：不要用
sudo npm install -g装 openrig 之外的工具时混用 sudo 和 nvm，nvm 管理的 Node 和系统 Node 的全局包路径不同，混用会导致命令找不到。
3.3 Windows 和 macOS 的安装差异
Windows 用户直接去 Node.js 官网下载 LTS 的 msi 安装包就行，安装时勾选“Add to PATH”。但要注意，如果你之前装过旧版，最好先在“应用和功能”里卸载干净再装新版，否则可能出现node命令指向旧目录的情况。macOS 用户如果用 Homebrew，brew install node@20然后brew link node@20 --force即可。Apple Silicon 的机器上，某些 npm 包的 native 模块需要 Rosetta 或者 arm64 版本，如果遇到mach-o file, but is an incompatible architecture报错，删掉node_modules和package-lock.json重装通常能解决。
4. openrig 的 YAML 配置详解
4.1 一个完整的 profile 应该包含哪些字段
假设 openrig 的配置文件叫openrig.yaml，放在项目根目录或者~/.config/openrig/下。一个典型的 Claude Code profile 大概长这样：
profiles: claude-deepseek: tool: claude model: deepseek-chat base_url: https://api.deepseek.com/anthropic api_key_env: DEEPSEEK_API_KEY extra_env: ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat args: - --dangerously-skip-permissions这里每个字段都有讲究。tool告诉 openrig 用哪个底层命令，model是传给工具的模型标识，base_url是 API 端点，api_key_env指定从哪个环境变量读密钥（这样 YAML 里不出现明文），extra_env是工具特有的额外环境变量，args是启动时附加的命令行参数。
Codex 的 profile 类似，但字段名可能不同：
codex-local: tool: codex model: qwen2.5-coder-32b base_url: http://localhost:1234/v1 api_key_env: LOCAL_API_KEY extra_env: OPENAI_API_KEY: dummy args: - --no-stream注意本地 LM Studio 或者 Ollama 通常不校验 API key，但 Codex 客户端可能强制要求这个变量存在，所以随便填个dummy就行。
4.2 多 profile 继承与覆盖的写法
openrig 如果支持 YAML 锚点或者自定义的继承机制，可以大幅减少重复配置。比如你有一组 profile 都走同一个公司内网网关，只是模型不同：
defaults: &defaults base_url: https://gateway.internal/v1 api_key_env: GATEWAY_KEY extra_env: NO_PROXY: localhost,127.0.0.1 profiles: claude-sonnet: <<: *defaults tool: claude model: claude-sonnet-4-20250514 claude-opus: <<: *defaults tool: claude model: claude-opus-4-20250514YAML 的锚点&defaults和引用<<: *defaults是标准语法，openrig 只要用常规的 YAML 解析库就能支持。这样改网关地址只需要改一处，所有 profile 自动生效。
4.3 敏感信息处理：环境变量与 .env 文件
绝对不要把 API key 明文写在 YAML 里，哪怕这个文件只在你本地。因为一旦你截图发群、提交到 git、或者用 AI 助手分析配置，key 就泄露了。正确做法是 YAML 里只写api_key_env: XXX，真正的 key 放在 shell 的.zshrc/.bashrc或者一个.env文件里，并且把.env加入.gitignore。
openrig 如果支持自动加载.env文件就更方便了。你可以在项目根目录放一个.env：
DEEPSEEK_API_KEY=sk-xxxxxxxx GATEWAY_KEY=sk-yyyyyyyy然后 openrig 启动时自动读取并注入到子进程环境里。这样团队协作时，每个人只需要维护自己的.env，YAML 配置可以共享。
5. 接入 Claude Code 与 Codex 的实操流程
5.1 Claude Code 安装与 openrig 集成
Claude Code 的安装方式取决于你用的平台。npm 全局安装是最通用的：
npm install -g @anthropic-ai/claude-code装完之后直接运行claude会引导你登录或者配置 API key。但如果你要走第三方 endpoint（比如 DeepSeek 的 Anthropic 兼容接口），就需要设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。用 openrig 的话，这些都在 YAML 里定义好了，直接：
openrig run claude-deepseekopenrig 内部会做几件事：读取 profile 配置、从指定环境变量取 key、设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY、然后 execclaude命令。你可以在args里加--model来覆盖默认模型，也可以加--verbose看详细日志。
实操心得：Claude Code 对
ANTHROPIC_SMALL_FAST_MODEL这个变量很敏感，如果你接的第三方 endpoint 不支持 Haiku 这类小模型，一定要在extra_env里把它设成和主模型一样的名称，否则 Claude Code 后台调用小模型做摘要时会报 model not found。
5.2 Codex 安装与常见报错处理
Codex 的安装通常也是 npm：
npm install -g @openai/codex但热搜词里出现了“codex无法加载组织设置”“your organization has disabled claude subscription access”这类报错，说明账号权限和订阅状态是高频问题。如果你用的是第三方 API 而不是官方订阅，需要在配置里明确指定base_url和api_key，并且把model设成第三方支持的名称。比如接 DeepSeek：
codex-deepseek: tool: codex model: deepseek-chat base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY启动后如果报the 'gpt-5.6-sol' model is not supported，说明 Codex 默认想用某个官方模型名，但你的 endpoint 不认。解决办法是在args里显式传--model deepseek-chat，或者在 YAML 的model字段里写对。
5.3 本地模型接入：LM Studio 与 Ollama
把 Claude Code 接到 LM Studio 的本地模型上，是很多人想做的事。LM Studio 启动本地 server 后，默认监听http://localhost:1234/v1，提供 OpenAI 兼容接口。但 Claude Code 要的是 Anthropic 格式的接口，所以不能直接接，需要中间加一层转换。有些工具（比如 claude-code-proxy 这类）可以做协议转换，openrig 如果内置了这个能力，那配置就很简单：
claude-local: tool: claude model: qwen2.5-coder-32b base_url: http://localhost:1234/anthropic api_key_env: LOCAL_KEY如果 openrig 不支持协议转换，那你就需要先启动一个转换代理，然后把base_url指向代理的地址。Ollama 的情况类似，它默认的 OpenAI 兼容端点是http://localhost:11434/v1，同样需要转换层才能给 Claude Code 用。
注意：本地模型跑 Claude Code 时，上下文长度和工具调用能力是关键瓶颈。很多 7B 或 13B 的模型不支持 function calling，Claude Code 的文件读写、终端执行功能会直接失效。建议至少用 32B 以上且明确支持 tool use 的模型。
6. 常见问题排查与避坑指南
6.1 连接失败类问题速查
| 报错信息 | 可能原因 | 排查步骤 |
|---|---|---|
cc switch local proxy failed while handling codex endpoint /responses | 代理层协议不匹配 | 检查代理是否支持 Codex 的 responses 端点，确认 base_url 路径是否正确 |
401 Unauthorized | API key 未注入或错误 | 用echo $DEEPSEEK_API_KEY确认变量存在，检查 openrig 的 api_key_env 字段拼写 |
model not supported | 模型名与 endpoint 不匹配 | 对照 endpoint 文档确认模型标识，注意大小写和版本后缀 |
ECONNREFUSED | 本地服务未启动或端口错误 | curl http://localhost:1234/v1/models测试连通性 |
organization has disabled access | 账号权限或订阅问题 | 确认使用的 key 所属账号有对应模型的访问权限 |
6.2 YAML 语法坑与排查技巧
YAML 的缩进必须用空格，而且同一层级缩进量必须一致。我见过最常见的错误是复制粘贴时混入了 Tab，解析器直接报found character '\t' that cannot start any token。排查方法是用cat -A openrig.yaml看有没有^I符号，有就是 Tab。
另一个坑是字符串里的特殊字符。比如 base_url 里如果有冒号，YAML 会把它当成键值分隔符，必须加引号：base_url: "https://example.com:8080/v1"。还有#号，如果出现在值里会被当成注释，也要加引号。
实操心得：写完 YAML 后，用
python -c "import yaml; yaml.safe_load(open('openrig.yaml'))"快速验证语法，比等 openrig 报错再排查快得多。
6.3 环境变量污染与隔离
前面提过，多个 AI 助手共用环境变量会互相干扰。openrig 如果做得好，应该在启动子进程时清空继承的环境变量，只注入 profile 里定义的。但如果你发现切换 profile 后行为不对，可以手动检查：
openrig run claude-deepseek --dry-run如果 openrig 支持 dry-run 模式，它会打印出将要设置的环境变量和执行的命令，但不实际启动。这样你就能确认有没有多余的变量泄漏进来。如果不支持，就在 profile 的extra_env里显式把不需要的变量设为空字符串，比如OPENAI_API_KEY: ""。
7. 团队协作与配置标准化
7.1 把 openrig.yaml 纳入版本控制
团队里每个人手动配环境是灾难的开始。正确的做法是把openrig.yaml提交到项目仓库，里面只包含非敏感的配置（tool、model、base_url、args），敏感信息通过.env文件或者 CI/CD 的 secret 注入。新人入职只需要 clone 仓库、装 Node.js、装 openrig、复制.env.example为.env并填入自己的 key，然后就能用统一的命令启动 AI 助手。
这样做的另一个好处是，当团队决定从 DeepSeek 切换到另一个模型服务时，只需要改 YAML 里的一行base_url和model，所有人 pull 一下就同步了，不用挨个通知。
7.2 多环境 profile 命名规范
建议按“工具-模型-环境”的格式命名 profile，比如claude-sonnet-prod、codex-deepseek-dev、claude-local-test。这样在 shell 里用 Tab 补全时能快速找到想要的。避免用default、test1这种无意义的名字，过两周你自己都忘了哪个是哪个。
如果 openrig 支持 profile 别名，可以再定义一层快捷方式：
aliases: c: claude-sonnet-prod x: codex-deepseek-dev然后openrig run c就能启动。这个功能看 openrig 具体实现，如果没有，用 shell alias 包一层也行。
7.3 配置变更的回归测试
每次改完 YAML，至少跑一遍冒烟测试：启动每个 profile，发一句“hello”看是否能正常返回。如果某个 profile 报错，先检查是不是 endpoint 挂了，再检查 key 是否过期，最后检查模型名是否被服务商下线。我习惯在 CI 里加一个定时任务，每天跑一次所有 profile 的连通性测试，这样服务商那边有变动能第一时间发现，而不是等到写代码写到一半才发现模型调不通。
8. 性能调优与进阶用法
8.1 启动速度优化
openrig 本身如果是个 Node.js CLI，启动时间通常在几百毫秒。但如果你在 profile 里加了健康检查或者代理启动逻辑，可能会拖慢到几秒。优化思路是：把健康检查做成可选的，默认关闭；代理进程用后台常驻模式，而不是每次启动都重新拉起。另外，Node.js 的冷启动可以通过--enable-source-maps关闭来稍微加快，但效果有限，主要瓶颈还是在网络请求上。
8.2 多模型 fallback 策略
如果 openrig 支持 fallback，可以这样配置：主模型超时或报错时自动切到备用模型。比如：
claude-with-fallback: tool: claude model: claude-sonnet-4-20250514 base_url: https://api.anthropic.com api_key_env: ANTHROPIC_KEY fallback: model: deepseek-chat base_url: https://api.deepseek.com/anthropic api_key_env: DEEPSEEK_API_KEY这样当 Anthropic 的接口不稳定时，自动降级到 DeepSeek，保证编码不中断。当然 fallback 的模型能力最好接近主模型，否则体验落差太大。
8.3 日志与审计
团队使用场景下，记录谁在什么时候用了哪个模型、消耗了多少 token，对成本控制很有帮助。openrig 如果支持日志输出，可以把每次启动的 profile 名称、时间戳、模型名写到一个 JSONL 文件里，后续用脚本分析。如果 openrig 本身不支持，可以在外层包一个 wrapper 脚本，在调用 openrig 前后打点。
注意：日志里不要记录 API key 和完整的请求内容，只记录元数据即可，避免敏感信息泄露。
9. 我踩过的几个坑
第一个坑是 YAML 里的布尔值陷阱。YAML 会把yes、no、on、off自动解析成布尔值，如果你某个字段的值恰好是这些词，就会类型错误。比如模型名如果叫on，必须加引号写成"on"。我遇到过 base_url 里包含no被解析成 false 的情况，排查了半天。
第二个坑是 Node.js 版本和 openrig 依赖不匹配。有次我用 Node 18 跑 openrig，报了一个crypto.hash is not a function的错误，升级到 Node 20 就好了。所以看到奇怪的 API 不存在报错，先检查 Node 版本。
第三个坑是代理环境变量。如果你的机器上设了HTTP_PROXY或HTTPS_PROXY，openrig 启动的子进程可能会继承这些变量，导致请求本地 LM Studio 时也走代理，然后连接失败。解决办法是在 profile 的extra_env里设NO_PROXY: localhost,127.0.0.1，或者启动前unset掉代理变量。
第四个坑是 Claude Code 的在线升级。热搜词里有“claude code在线升级最新版本”，说明版本迭代很快。但升级后有时配置格式会变，比如某个环境变量改名了，或者某个参数废弃了。我的建议是锁定一个稳定版本，不要盲目追新，等社区反馈没问题了再升。如果 openrig 能管理工具版本就更好了，但目前看可能还需要手动控制。
10. 后续可以怎么扩展
openrig 目前聚焦在配置管理和启动封装上，但沿着这个思路可以做的事情不少。比如加一个openrig doctor命令，自动检查 Node 版本、工具是否安装、环境变量是否齐全、endpoint 是否可达，把常见问题一次性诊断出来。再比如加一个openrig bench命令，对同一个 prompt 在不同模型上跑一遍，对比响应速度和输出质量，帮团队选型。
另一个方向是和编辑器集成。VS Code 里已经有 Claude Code 和 Codex 的插件，如果 openrig 能暴露一个本地 API，让编辑器插件读取当前激活的 profile，就能实现“在编辑器里切换模型”而不用改配置文件。这个需要 openrig 提供一个轻量的 daemon 或者 socket 接口，实现难度不大，但能显著提升日常使用体验。
我个人在实际操作中的体会是，配置管理工具的价值不在于功能多花哨，而在于把“每次都要手动做且容易做错”的事情变成“一次配置、处处可用”。openrig 如果能把 YAML 解析、环境隔离、多工具适配这三件事做扎实，就已经解决了 AI 编程助手日常使用中 80% 的摩擦。剩下的 20%，靠社区踩坑和文档补全就够了。
