1. 从 openrig 说起一个被低估的本地 AI 编码环境编排工具第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者机械臂项目毕竟 “rig” 这个词在工程领域通常指“装配台”“机架”。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编码助手并且被各种配置文件、模型接入、代理转发搞得头大那你大概率已经在某个 issue 或者讨论帖里见过它。openrig 本质上是一个面向本地 AI 编码工具的环境编排与配置管理层它要解决的核心问题只有一个让你用一份 YAML 文件把 Claude Code、Codex 以及它们背后要调用的模型服务、代理端点、环境变量全部串起来而不是每次换模型、换机器都手动改一堆配置。我最初接触 openrig 是因为一个很具体的痛点。手上有三台开发机一台 macOS 日常写代码一台 Ubuntu 跑训练和推理还有一台 Windows 偶尔做演示。每台机器上都装了 Claude Code 和 Codex CLI但模型来源不一样macOS 上接的是官方订阅Ubuntu 上想接本地 LM Studio 或者 DeepSeek 的 APIWindows 上则经常要切换不同的第三方端点做对比测试。结果就是每换一次环境就要重新翻文档、改~/.claude/settings.json、改 Codex 的config.toml、设置ANTHROPIC_BASE_URL、OPENAI_BASE_URL这些环境变量稍有不慎就是cc switch local proxy failed while handling codex endpoint /responses这种让人抓狂的报错。openrig 的出现让这套流程变得可控。它用 YAML 作为唯一的配置入口把“用哪个工具”“调哪个模型”“走哪个端点”“注入哪些环境变量”这几件事解耦开来。你不再需要记住每个工具各自的配置路径和字段名只需要在 openrig 的配置文件里声明清楚剩下的交给它去生成、注入、切换。这篇文章我会从实际使用角度出发把 openrig 的设计思路、YAML 配置细节、Node.js 环境准备、Claude Code 与 Codex 的接入实操、以及我踩过的那些坑完整地拆一遍。适合已经装过 Claude Code 或 Codex、但被多环境配置折磨过的开发者也适合刚接触这类工具、想一步到位把环境搭好的新手。2. openrig 的整体设计思路与方案选型2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置格式这个决定背后有很实际的考量。Claude Code 自己的配置文件是 JSONCodex 用的是 TOML如果 openrig 再用第三种格式那用户就要同时维护三套语法。YAML 的优势在于它对层级嵌套和注释的支持都比 JSON 和 TOML 更自然。JSON 不能写注释TOML 在深层嵌套时表头会变得很长而 openrig 的配置里经常需要描述“某个工具在某个场景下调用某个端点的某个模型”这种三四层的结构用 YAML 写出来最直观。举个例子你要配置 Claude Code 在“本地开发”场景下走 LM Studio在“远程测试”场景下走 DeepSeek用 YAML 可以写成profiles: local-dev: tool: claude-code provider: type: openai-compatible base_url: http://127.0.0.1:1234/v1 model: qwen2.5-coder-32b remote-test: tool: claude-code provider: type: openai-compatible base_url: https://api.deepseek.com/v1 model: deepseek-chat这种写法一眼就能看出层级关系改起来也不容易出错。如果用 JSON光是引号和逗号就够你调半天。所以 openrig 选 YAML 不是为了赶时髦而是因为在这个特定场景下YAML 的可读性和可维护性确实更好。2.2 编排层与执行层分离的核心逻辑openrig 的架构里有一个很重要的设计原则编排层不直接参与模型调用。它做的事情是读取 YAML、解析出当前 profile、然后把对应的环境变量和配置文件写到正确的位置最后启动 Claude Code 或 Codex 的进程。真正的模型请求还是由 Claude Code 或 Codex 自己发出的。这个设计的好处是 openrig 不需要关心各家 API 的协议差异也不需要处理流式响应、token 计数这些细节。它只负责“把环境准备好”剩下的交给工具本身。这样做的好处是升级和维护成本低Claude Code 或 Codex 更新了只要它们的配置接口没变openrig 就不用跟着改。坏处是如果某个工具的配置方式发生重大变化openrig 需要适配但这种情况并不频繁。我在实际使用中感受到的另一个好处是调试变得简单。当出现cc switch local proxy failed while handling codex endpoint /responses这类错误时我可以先用 openrig 把环境变量导出到当前 shell然后手动运行 Codex 的命令行看看到底是端点不通、模型名不对、还是认证头缺失。因为 openrig 不拦截请求所以问题定位的链路很短。2.3 与 Claude Code、Codex 原生配置的关系需要明确一点openrig 不是要取代 Claude Code 和 Codex 自己的配置系统而是在它们之上做了一层配置生成和切换。Claude Code 读取的是~/.claude/settings.json或者项目目录下的.claude/settings.jsonCodex 读取的是~/.codex/config.toml。openrig 会根据你选择的 profile把对应的内容写入这些文件或者通过环境变量注入。这意味着两件事。第一你随时可以脱离 openrig手动去改这些原生配置文件效果是一样的。第二如果你之前已经手动配置过 Claude Code 或 Codex迁移到 openrig 的时候需要把已有的配置翻译成 openrig 的 YAML 格式。这个过程不复杂但需要你清楚自己原来配了什么。我建议在迁移之前先备份原来的配置文件这样万一 openrig 的生成结果不符合预期可以快速回滚。3. 环境准备Node.js 与基础依赖的安装细节3.1 Node.js 版本选择与安装方式对比openrig 本身是一个 Node.js 工具Claude Code 和 Codex CLI 也都是基于 Node.js 的。所以第一步是把 Node.js 装好。这里有一个很常见的坑网上很多教程让你直接apt install nodejs但 Ubuntu 官方源里的 Node.js 版本往往很旧而 Claude Code 和 Codex 对 Node.js 版本有要求通常需要 18 以上推荐 20 LTS 或更高。我在 Ubuntu 上试过几种安装方式对比下来最稳的是用 NodeSource 的源或者 nvm。NodeSource 的方式适合需要全局安装、多用户共享的场景curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完之后用node -v确认版本。如果你看到的是v20.x.x就对了。如果遇到error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错通常是因为你指定的版本号在源里还不存在换成setup_20.x或者setup_22.x这种稳定版本即可。nvm 的方式更适合需要频繁切换 Node.js 版本的开发者curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20nvm 的好处是每个项目可以用不同的 Node.js 版本而且不需要 sudo 权限。缺点是 shell 配置稍微麻烦一点新开的终端要确保 nvm 的初始化脚本被加载了。macOS 上直接用 Homebrew 最省事brew install node20。Windows 上建议去 Node.js 官网下载 LTS 版本的安装包不要用 Microsoft Store 里的版本那个版本在权限和路径处理上经常出问题。3.2 包管理器与全局安装路径的坑Node.js 装好之后下一步是安装 openrig、Claude Code 和 Codex。这里有一个很容易被忽略的问题全局安装路径的权限。如果你用npm install -g的时候没有权限写入/usr/lib/node_modules就会报 EACCES 错误。解决办法有两个一是用 nvm 管理 Node.js这样全局包会装到用户目录下不需要 sudo二是手动配置 npm 的全局路径mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到~/.bashrc或~/.zshrc里然后source一下。这样以后npm install -g就不会再有权限问题了。我个人的习惯是能用 nvm 就用 nvm因为它在多版本切换和权限隔离上都更干净。只有在 CI 环境或者 Docker 镜像里我才会用 NodeSource 的方式直接装系统级的 Node.js。3.3 验证安装与常见报错处理装完 Node.js 和 npm 之后建议按顺序验证几个东西。先node -v和npm -v确认版本。然后npm config get registry确认 registry 是可访问的。如果你在国内网络环境下遇到安装慢或者超时可以临时切换到国内镜像源npm config set registry https://registry.npmmirror.com但要注意有些包在镜像源上同步不及时如果安装失败可以切回官方源再试。安装 openrig 的时候如果遇到npm ERR! code ERESOLVE这种依赖冲突可以先试npm install -g openrig --legacy-peer-deps这是 npm 7 以后比较常见的兼容性问题。还有一个坑是Node.js 版本和原生模块的兼容性。有些依赖包包含 C 原生模块在不同 Node.js 版本之间需要重新编译。如果你在 nvm 下切换了 Node.js 版本最好把全局包重新装一遍否则可能出现NODE_MODULE_VERSION不匹配的错误。4. openrig 的 YAML 配置详解与实操4.1 配置文件结构与核心字段说明openrig 的配置文件通常放在~/.openrig/config.yaml也可以通过--config参数指定其他路径。一个完整的配置包含三个主要部分providers、tools和profiles。providers定义模型服务的端点信息tools定义 Claude Code 和 Codex 的启动参数profiles把前两者组合起来形成可以直接切换的场景。先看providers部分providers: lmstudio: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder-32b - deepseek-coder-v2 deepseek: type: openai-compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} models: - deepseek-chat - deepseek-coder这里有几个关键点。type字段目前主要支持openai-compatible和anthropic两种前者用于大多数第三方端点和本地推理服务后者用于官方 Anthropic API。api_key支持环境变量插值写成${DEEPSEEK_API_KEY}就会从环境变量里读取这样就不用把密钥明文写在 YAML 里。models列表是可选的但建议写上因为 openrig 在切换 profile 的时候会校验模型名是否在列表里能提前发现拼写错误。4.2 为 Claude Code 配置本地 LM Studio 模型Claude Code 默认走的是 Anthropic 的 API但通过设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY可以把它指向任何兼容 Anthropic 消息格式的端点。不过 LM Studio 默认提供的是 OpenAI 兼容接口不是 Anthropic 格式。所以这里需要一个转换层或者使用 LM Studio 的 Anthropic 兼容模式较新版本支持。假设你的 LM Studio 已经加载了qwen2.5-coder-32b模型并且开启了本地服务监听在1234端口。openrig 的 profile 可以这样写profiles: claude-local: tool: claude-code provider: lmstudio model: qwen2.5-coder-32b env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234/v1 ANTHROPIC_API_KEY: lm-studio ANTHROPIC_MODEL: qwen2.5-coder-32b然后运行openrig use claude-localopenrig 会把这些环境变量注入到当前 shell或者写入 Claude Code 的配置文件。具体行为取决于你的 openrig 版本和配置有些版本是生成一个env文件让你 source有些是直接修改~/.claude/settings.json。我实测下来直接注入环境变量的方式更灵活因为 Claude Code 对环境变量的优先级高于配置文件。你可以在一个终端里用本地模型在另一个终端里用官方 API互不干扰。4.3 为 Codex 接入 DeepSeek 的完整配置Codex 的配置方式和 Claude Code 略有不同。Codex CLI 读取~/.codex/config.toml里面可以定义多个 model provider。openrig 在生成 Codex 配置的时候会把 YAML 里的 provider 信息转换成 TOML 格式。一个典型的 Codex DeepSeek 配置如下profiles: codex-deepseek: tool: codex provider: deepseek model: deepseek-chat env: OPENAI_BASE_URL: https://api.deepseek.com/v1 OPENAI_API_KEY: ${DEEPSEEK_API_KEY}运行openrig use codex-deepseek之后openrig 会更新~/.codex/config.toml里的model_provider和model字段同时确保环境变量在启动 Codex 时可用。这里要注意Codex 对OPENAI_BASE_URL的路径处理比较严格如果端点路径不对就会出现cc switch local proxy failed while handling codex endpoint /responses这类错误。DeepSeek 的兼容端点是https://api.deepseek.com/v1不要多加或者少加/v1。4.4 多 Profile 切换与场景化管理openrig 最实用的功能之一是 profile 切换。你可以定义多个 profile分别对应不同的使用场景profiles: daily: tool: claude-code provider: anthropic-official model: claude-sonnet-4-20250514 local-heavy: tool: claude-code provider: lmstudio model: qwen2.5-coder-32b codex-test: tool: codex provider: deepseek model: deepseek-chat切换的时候只需要openrig use daily或者openrig use local-heavy。openrig 会处理好配置文件更新和环境变量注入。我通常会在项目根目录放一个.openrig.yaml里面指定这个项目默认用哪个 profile这样进入项目目录后运行openrig use不带参数就会自动加载项目级配置。注意profile 名称不要用中文或者特殊字符虽然 YAML 支持但在 shell 里切换的时候容易出问题。用英文短横线分隔是最稳妥的。5. Claude Code 与 Codex 的安装与联调实操5.1 Claude Code 安装与 VS Code 集成Claude Code 的安装方式取决于你的使用场景。如果你只在终端里用直接npm install -g anthropic-ai/claude-code就行。如果你想在 VS Code 里用需要安装 Claude Code 的 VS Code 扩展然后在设置里配置 Claude Code 的可执行文件路径。安装完成后第一次运行claude会引导你登录。如果你用的是官方订阅直接按提示走 OAuth 流程。如果你用的是第三方端点或者本地模型可以跳过登录直接通过环境变量指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。VS Code 集成有一个细节需要注意扩展和终端使用的是同一套配置。也就是说如果你在终端里通过 openrig 切换了 profileVS Code 里的 Claude Code 也会跟着变。这既是好事也是坏事。好处是配置统一坏处是你没法在 VS Code 里用官方模型、同时在终端里用本地模型。如果你有这种需求可以考虑用 VS Code 的 workspace 设置来覆盖环境变量。5.2 Codex 安装与 Windows 桌面版注意事项Codex 的安装相对直接npm install -g openai/codex。安装完成后运行codex会进入交互式界面。Codex 支持多种登录方式包括 API key 和 OAuth。如果你要接入 DeepSeek 或者其他第三方端点建议直接用 API key 方式然后在 openrig 里配置好OPENAI_BASE_URL。Windows 桌面版的 Codex 有一个已知问题路径分隔符和换行符的处理。如果你在 WSL 里用 Codex配置文件路径是 Linux 风格的没问题。但如果你在原生 Windows 的 PowerShell 或者 CMD 里用~/.codex/config.toml会被解析成C:\Users\你的用户名\.codex\config.toml这个路径通常是对的但如果你的用户名包含空格或者中文就可能出问题。解决办法是把 Codex 的配置目录通过环境变量CODEX_HOME指定到一个没有空格和中文的路径。另外Windows 上安装 Codex 的时候如果遇到codex无法加载组织设置这类错误通常是因为网络请求被拦截或者认证信息过期。可以先检查OPENAI_API_KEY是否设置正确然后确认端点是否可达。5.3 联调验证从 openrig 到模型响应的完整链路配置完成之后需要做一次完整的联调验证。我通常按这个顺序来运行openrig use profile确认没有报错。运行openrig env查看当前注入的环境变量是否符合预期。运行claude --version或codex --version确认工具能正常启动。在 Claude Code 或 Codex 里发一条简单的测试消息比如“用 Python 写一个快速排序”看是否能收到响应。如果第三步就失败了说明环境变量或者配置文件有问题。如果第三步成功但第四步失败说明端点或者模型名有问题。这时候可以手动用curl测试端点curl -X POST http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-coder-32b,messages:[{role:user,content:hi}]}如果curl能通但 Claude Code 不通那大概率是 Claude Code 的请求格式和端点不兼容。这时候需要检查 LM Studio 是否开启了 Anthropic 兼容模式或者考虑用一个轻量的转换代理。6. 常见问题与排查技巧实录6.1 端点与模型相关报错速查报错信息可能原因排查方法cc switch local proxy failed while handling codex endpoint /responses端点路径错误或代理未启动检查OPENAI_BASE_URL是否包含/v1确认本地服务监听端口the gpt-5.6-sol model is not supported when using codex with a...模型名不在端点支持列表中用curl查询端点的/models接口确认可用模型名your organization has disabled claude subscription access for claude code组织策略限制或订阅过期检查 Anthropic 账户状态或改用 API key 方式error installing 24.21.0: node.js v24.21.0 is not yet releasedNode.js 版本号不存在改用setup_20.x或setup_22.xcodex无法加载组织设置认证信息缺失或网络问题检查OPENAI_API_KEY确认端点可达这张表是我在实际使用中整理出来的覆盖了大部分常见问题。遇到报错的时候先查表能省不少时间。6.2 本地模型接入的延迟与超时处理本地模型接入最常见的问题不是配置错误而是延迟和超时。LM Studio 加载一个 32B 的模型首次推理可能需要几秒钟甚至更久。Claude Code 和 Codex 默认的超时时间可能不够导致请求被中断。解决办法是在 openrig 的 profile 里增加超时配置profiles: claude-local: tool: claude-code provider: lmstudio model: qwen2.5-coder-32b env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234/v1 ANTHROPIC_API_KEY: lm-studio ANTHROPIC_MODEL: qwen2.5-coder-32b API_TIMEOUT_MS: 120000API_TIMEOUT_MS这个环境变量不是所有版本都支持但较新的 Claude Code 版本可以识别。如果不行可以考虑在本地起一个轻量代理专门处理超时和重试逻辑。另一个技巧是预热模型。在开始编码之前先手动发一条简单的请求让模型加载到显存里。这样后续的请求就不用等加载时间了。我通常会在 openrig 的 profile 里加一个prewarm脚本切换 profile 之后自动发一条预热请求。6.3 配置文件冲突与备份策略openrig 会修改 Claude Code 和 Codex 的原生配置文件这就带来一个风险手动修改和 openrig 生成的内容互相覆盖。我的做法是一旦决定用 openrig 管理配置就不再手动去改~/.claude/settings.json和~/.codex/config.toml。所有变更都通过 openrig 的 YAML 来做。同时我会在 openrig 的配置目录里保留一份备份cp ~/.claude/settings.json ~/.openrig/backups/claude-settings-$(date %Y%m%d).json cp ~/.codex/config.toml ~/.openrig/backups/codex-config-$(date %Y%m%d).toml这样万一 openrig 生成了错误的配置可以快速恢复。openrig 本身也支持openrig backup和openrig restore命令但手动备份更可控。提示如果你在团队里共享 openrig 配置不要把包含 API key 的 YAML 提交到 Git。用环境变量插值然后在 CI 或者本地环境里设置对应的密钥。6.4 网络环境与镜像源的选择建议Node.js 包的安装速度受网络环境影响很大。如果你在安装 openrig、Claude Code 或 Codex 的时候遇到超时可以尝试以下顺序先试官方源确认是否能通。如果超时切换到国内镜像源https://registry.npmmirror.com。如果镜像源上某些包版本不全可以针对特定包临时切回官方源。对于模型端点的访问本地 LM Studio 不涉及网络问题。但如果你用的是 DeepSeek 或者其他云端 API需要确认端点可达。可以用curl -I测试连通性curl -I https://api.deepseek.com/v1/models如果返回 401 或者 403说明网络是通的只是认证信息不对。如果直接超时那就是网络问题需要检查代理设置或者 DNS 解析。7. 一些实操心得与后续扩展思路openrig 这个工具本身还在快速迭代中我用的版本和最新的版本在配置字段上可能有差异。但核心思路是不变的用一份声明式的配置管理多个 AI 编码工具和多个模型端点之间的组合关系。这个思路的价值在于它把“环境配置”这件事从手工操作变成了可版本化、可复用、可切换的工程实践。我在实际使用中最大的体会是不要试图一次性把所有场景都配好。先配一个最常用的 profile跑通之后再逐步增加。每增加一个 profile就做一次完整的联调验证。这样出问题的时候排查范围很小容易定位。另外openrig 的 YAML 配置可以和 dotfiles 仓库结合。把~/.openrig/config.yaml纳入版本管理换机器的时候直接 clone 下来改一下环境变量就能用。这比手动装一遍、配一遍要快得多。后续如果 openrig 支持了更多的工具类型比如 Cursor、Windsurf 这些编辑器的 AI 功能那这套配置管理的价值会更大。目前来看Claude Code 和 Codex 是终端 AI 编码工具里最活跃的两个openrig 先把这两个支持好已经能覆盖大部分开发者的日常需求了。