1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟“rig”这个词在工程领域通常跟设备、装置挂钩。但翻了一圈社区讨论和实际代码之后才明白它其实是一个围绕 AI 编程助手做本地化编排的开源工具集核心解决的是把 Claude Code、Codex 这类命令行 AI 助手统一管理起来的问题。说白了你平时可能同时用着好几个 AI 编程工具每个都有自己的配置目录、认证方式、模型接入参数时间一长就乱成一锅粥openrig 想做的就是把这些东西收拢到一个可切换、可复用的框架里。我接触这个项目的契机很实际。手头同时跑着 Claude Code 和 Codex前者接的是官方订阅后者有时候要切到本地模型或者第三方兼容接口做测试。每次切换都要改配置文件、重启终端、重新登录偶尔还会因为环境变量冲突导致某个工具直接罢工。openrig 的出现让我看到了一个统一入口的可能性它不替代这些工具本身而是在它们之上做了一层编排和代理转发。从热词分布来看大家关心的焦点集中在几个方向Claude Code 和 Codex 的安装配置、Node.js 环境搭建、tmux 会话管理、本地模型接入、以及各种代理切换失败的排查。这些恰好就是 openrig 要处理的核心场景。它适合那些已经在用或者准备用 AI 编程助手、但被多工具配置管理折磨过的开发者尤其是习惯在终端里干活、对 Node.js 生态不陌生的人。需要提前说明的是openrig 本身不是一个模型也不提供模型能力它更像是一个“调度台”。你原来的 Claude Code 还是 Claude CodeCodex 还是 Codex只是它们启动时读取的配置、走的网络路径、用的认证信息可以由 openrig 来统一分配。理解这一点很关键否则很容易把它当成某个万能客户端结果发现跟自己预期不符。2. 为什么需要 openrig 这层编排2.1 多 AI 编程助手并存的现实困境现在做开发的人手里同时握着两三个 AI 编程助手太正常了。Claude Code 在代码理解和长上下文方面表现稳定Codex 在某些补全场景和特定语言上响应更快还有人会接本地部署的模型做离线推理。每个工具都有自己的脾气Claude Code 依赖~/.claude目录下的配置和订阅认证Codex 有自己的~/.codex配置体系和登录态本地模型接入又涉及 API 地址、密钥、模型名称映射等一堆参数。问题在于这些配置之间经常打架。比如你为了让 Codex 走本地模型改了它的 endpoint 配置结果 Claude Code 的某个代理设置也被影响到了。又比如你在 tmux 里开了好几个窗口分别跑不同的助手环境变量互相污染排查起来非常头疼。我遇到过最典型的情况是Codex 报 “cc switch local proxy failed while handling codex endpoint /responses”表面看是代理转发失败实际上是上游配置里模型名称写错了但错误信息完全不指向根因。openrig 的思路是把这些工具的启动过程抽象成“配置档”profile每个档位定义清楚用哪个工具、走哪个模型、用什么认证、监听哪个端口。切换的时候不需要手动改文件而是通过 openrig 的命令行接口选择对应档位由它来注入环境变量和启动参数。这样各个工具的配置目录保持独立互不干扰同时又能共享一些公共设置。2.2 本地模型接入的刚需热词里频繁出现“claude code 调用 lmstudio 的本地模型”“codex 接入 deepseek”这类搜索说明很多人有把 AI 编程助手接到本地或第三方模型上的需求。原因无非几种官方订阅额度不够用、想用特定模型做专项任务、或者单纯想省点费用。但每个工具接入外部模型的方式都不一样Claude Code 需要通过环境变量指定 base URL 和 API keyCodex 有自己的 provider 配置格式稍有不慎就会遇到 “model is not supported” 或者 “organization has disabled” 之类的报错。openrig 在这方面的价值在于它把不同工具的模型接入配置做了归一化处理。你只需要在 openrig 的配置里写一次模型端点信息它就能按照各个工具要求的格式分别生成对应的配置片段。比如同一个本地模型服务Claude Code 需要的是ANTHROPIC_BASE_URL加ANTHROPIC_API_KEYCodex 需要的是model_provider加base_urlopenrig 帮你把映射关系处理好省得你对着两套文档来回翻。2.3 tmux 会话管理的天然契合tmux 在热词里出现不是偶然。用 AI 编程助手的人很多都习惯在 tmux 里开多个 pane一个跑 Claude Code 做代码审查一个跑 Codex 做补全测试还有一个跑本地模型服务。但 tmux 会话恢复之后环境变量不会自动重新加载经常出现“昨天还能用今天打开就报认证失败”的情况。openrig 如果跟 tmux 结合得好可以在会话创建时自动注入正确的环境变量恢复会话时也能重新初始化配置这对重度终端用户来说是个不小的痛点。我自己的做法是在 tmux 的session-created钩子里调用 openrig 的初始化命令让它根据当前项目目录自动选择对应的配置档。这样每个项目目录下打开 tmuxAI 助手自动就是配好的状态不需要手动 source 任何脚本。这个思路后面在实操部分会详细展开。3. 核心组件与配置细节拆解3.1 Node.js 环境版本选择与安装方式openrig 本身是 Node.js 项目所以第一步绕不开 Node.js 环境。热词里“node.js安装”“ubuntu安装node.js 20”“node.js lts下载”出现频率很高说明不少人在这一步就卡住了。我的建议很明确用 LTS 版本不要追最新。Node.js 的奇数版本是非稳定版偶数版本才是 LTSopenrig 这类工具通常只保证在 LTS 上稳定运行。在 Ubuntu 上安装 Node.js 20我不推荐直接用apt install nodejs因为系统源里的版本往往偏旧。更稳妥的方式是用 NodeSource 的仓库或者 nvm。nvm 的好处是可以在不同项目间切换 Node 版本坏处是跟 tmux 结合时需要额外处理 shell 初始化。如果你跟我一样主要在 tmux 里干活用 NodeSource 装系统级 Node 会更省心。具体操作上先确认当前版本node -v npm -v如果版本低于 18就需要升级。用 NodeSource 的方式curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完之后再确认一次版本确保node -v输出的是 v20.x。这里有个坑有些系统里同时存在 snap 版的 node 和 apt 版的 nodewhich node可能指向 snap 的路径导致版本混乱。用which -a node可以列出所有 node 可执行文件的位置把不需要的从 PATH 里去掉。注意如果你之前用 nvm 装过 Node后来又用 apt 装了一个shell 启动时 nvm 的初始化脚本可能会把 PATH 改回去。检查~/.bashrc或~/.zshrc里 nvm 相关行的位置确保它不会覆盖系统级的 Node 路径。3.2 Claude Code 与 Codex 的配置隔离Claude Code 默认读取~/.claude目录下的配置Codex 默认读取~/.codex。openrig 要做编排首先得保证这两个目录的内容不会被互相覆盖。我的做法是在 openrig 的配置里为每个工具指定独立的配置根目录比如tools: claude: config_dir: ~/.openrig/profiles/claude env: ANTHROPIC_BASE_URL: http://localhost:1234 ANTHROPIC_API_KEY: local-key codex: config_dir: ~/.openrig/profiles/codex env: OPENAI_BASE_URL: http://localhost:1234/v1 OPENAI_API_KEY: local-key这样每个工具启动时openrig 会把对应的config_dir软链接或者复制到工具默认读取的位置或者通过环境变量告诉工具去读指定目录。具体用哪种方式取决于工具本身是否支持自定义配置路径。Claude Code 对CLAUDE_CONFIG_DIR环境变量有支持Codex 也有类似的机制openrig 就是利用这些入口来做隔离的。这里要特别小心的是认证信息的处理。Claude Code 的订阅认证和 API key 认证是两套逻辑如果你同时配置了订阅登录和 API key可能会出现 “your organization has disabled claude subscription access” 这类提示。openrig 在切换配置档时应该把不相关的认证方式清理掉避免冲突。3.3 代理转发与 endpoint 映射热词里 “cc switch local proxy failed while handling codex endpoint /responses” 这个报错很有代表性。它说的是代理层在转发 Codex 的/responses请求时失败了。这类问题通常有三个原因上游模型服务没有正确响应/responses路径、请求体格式不匹配、或者模型名称不被支持。openrig 如果内置了代理转发功能就需要处理不同工具和不同模型服务之间的协议差异。Claude Code 用的是 Anthropic 的 messages 格式Codex 用的是 OpenAI 的 responses 格式本地模型服务可能只支持其中一种或者两种都不完全支持。代理层的职责就是做格式转换和路径重写。我在配置本地模型接入时会先用 curl 直接测试模型服务的原始接口确认它能正常响应然后再通过 openrig 的代理层走一遍对比两次的请求和响应差异。这样能快速定位是模型服务本身的问题还是代理转换的问题。具体测试命令curl -X POST http://localhost:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:local-model,messages:[{role:user,content:test}]}如果这个能通但通过 openrig 走 Codex 就不行那问题大概率出在格式转换上。这时候需要看 openrig 的代理日志确认它把 Codex 的请求转成了什么格式发给上游。3.4 tmux 集成与自动化初始化tmux 和 openrig 的结合点在于会话生命周期管理。我通常会在~/.tmux.conf里加这样一段set-hook -g session-created run-shell openrig init --auto set-hook -g client-attached run-shell openrig refreshsession-created钩子在新建会话时触发openrig init --auto会根据当前工作目录查找最近的 openrig 配置文件然后初始化对应的环境。client-attached钩子在重新连接会话时触发openrig refresh用来重新加载可能已经过期的认证信息或模型端点。这个方案有个前提openrig 的init命令要能快速执行不能阻塞 tmux 会话创建。如果初始化过程涉及网络请求或者耗时操作最好放到后台异步执行或者加超时控制。我实测下来纯本地配置加载在 100ms 以内对 tmux 体验没有明显影响。提示如果你在 tmux 里用 nvm 管理 Node 版本session-created钩子执行时可能 nvm 还没初始化。解决办法是在钩子里显式 source nvm 的脚本或者把 openrig 装成全局可执行文件不依赖当前 shell 的 Node 环境。4. 从零搭建 openrig 工作流的完整实操4.1 环境准备与依赖安装开始之前确认系统里有这些基础组件Node.js 20、npm 或 yarn、git、tmux。在 Ubuntu 上一条命令搞定sudo apt update sudo apt install -y git tmux curlNode.js 按上一节说的方法装好。然后从仓库克隆 openriggit clone https://github.com/your-org/openrig.git cd openrig npm install npm run build如果项目提供了全局安装方式比如npm install -g .那就直接装到全局这样在任何目录下都能调用openrig命令。装完之后验证openrig --version openrig --help能正常输出版本和帮助信息说明基础环境没问题。4.2 配置文件编写与档位定义openrig 的核心配置文件通常放在项目根目录或者用户主目录下命名为openrig.yaml或openrig.json。我习惯用 YAML可读性好一些。一个典型的配置结构如下version: 1 profiles: claude-local: tool: claude model: local-qwen endpoint: http://localhost:1234 api_key: local-key config_dir: ~/.openrig/profiles/claude-local codex-local: tool: codex model: local-deepseek endpoint: http://localhost:1234/v1 api_key: local-key config_dir: ~/.openrig/profiles/codex-local claude-official: tool: claude model: claude-sonnet auth: subscription config_dir: ~/.openrig/profiles/claude-official models: local-qwen: provider: openai-compatible base_url: http://localhost:1234/v1 model_name: qwen2.5-coder local-deepseek: provider: openai-compatible base_url: http://localhost:1234/v1 model_name: deepseek-coder每个 profile 定义了一个可启动的配置档指定用哪个工具、接哪个模型、走什么认证、配置目录在哪。models 部分定义模型端点的公共信息profile 里引用模型名称即可。这样改模型地址只需要改一处所有引用它的 profile 都会生效。写配置的时候要注意 YAML 的缩进用空格不用 tab。另外~在 YAML 里不会被自动展开成用户主目录openrig 如果支持的话会在读取时处理如果不支持就需要写绝对路径。我一般直接写绝对路径省得踩坑。4.3 启动与切换的实操演示配置写好后启动一个 profileopenrig start claude-local这个命令会做几件事根据 profile 里的config_dir准备配置目录、把模型端点和密钥写入工具能识别的环境变量或配置文件、然后启动 Claude Code。如果一切正常你会看到 Claude Code 的交互界面并且它使用的是你指定的本地模型。切换 profile 的时候先停掉当前的openrig stop然后启动新的openrig start codex-local如果 openrig 支持热切换可能还有openrig switch codex-local这样的命令不用手动 stop 再 start。具体看项目实现。在 tmux 里我通常这样用tmux new-session -d -s ai-work tmux send-keys -t ai-work openrig start claude-local Enter tmux split-window -h -t ai-work tmux send-keys -t ai-work openrig start codex-local Enter这样左右两个 pane 分别跑 Claude Code 和 Codex各自用不同的模型配置互不干扰。tmux 的session-created钩子会自动处理环境初始化不需要手动 source 任何东西。4.4 本地模型接入的参数计算与验证接入本地模型时有几个参数需要仔细确认。首先是模型名称必须跟模型服务实际加载的名称完全一致大小写敏感。其次是上下文长度本地模型的上下文窗口通常比云端模型小如果 Claude Code 或 Codex 发送的请求超过了模型的最大上下文会直接报错。你需要根据模型的实际能力调整工具的max_tokens或context_window设置。以 Qwen2.5-Coder 7B 为例它的上下文窗口是 32K token。Claude Code 默认可能按 200K 上下文来构造请求这时候就需要在 openrig 的 profile 里加一个覆盖参数profiles: claude-local: tool: claude model: local-qwen endpoint: http://localhost:1234 api_key: local-key config_dir: ~/.openrig/profiles/claude-local overrides: max_context_tokens: 32768 max_output_tokens: 4096max_context_tokens告诉工具不要发送超过这个长度的请求max_output_tokens限制模型单次输出的最大长度。这两个值需要根据模型的实际能力来设设大了会报错设小了会影响效果。验证接入是否成功最直接的方法是发一个简单请求看响应openrig test claude-local --prompt 写一个 Python 快速排序如果返回了正常的代码说明链路通了。如果报错看错误信息指向哪个环节是连接不上模型服务、还是认证失败、还是模型名称不匹配、还是上下文超限。每个错误对应的排查方向不同下一节会详细展开。5. 常见报错与排查技巧实录5.1 代理转发失败的典型场景“cc switch local proxy failed while handling codex endpoint /responses” 这个报错我遇到过好几次每次原因都不太一样。整理了一个排查表报错关键词可能原因排查方法endpoint /responses failed上游模型服务不支持 responses 格式用 curl 直接测试上游的 /v1/chat/completions 和 /v1/responsesmodel is not supported模型名称不匹配或模型未加载检查模型服务实际加载的模型名确认与配置一致organization has disabled认证方式冲突订阅和 API key 同时存在清理不需要的认证配置只保留一种unrecognized configuration setting配置文件里有工具不认识的字段对照工具文档检查配置项拼写node.js v24.21.0 is not yet releasedNode 版本号写错或源里没有该版本改用 LTS 版本如 20.x代理转发失败最常见的原因是格式不兼容。Codex 发送的是 OpenAI responses 格式的请求而很多本地模型服务只支持 chat completions 格式。openrig 的代理层需要做格式转换如果转换逻辑有 bug 或者配置不对就会在转发时失败。我的做法是打开 openrig 的调试日志看它实际发给上游的请求体长什么样然后跟模型服务期望的格式做对比。5.2 认证与登录问题的处理Claude Code 和 Codex 的认证机制不同混用的时候容易出问题。Claude Code 支持订阅登录和 API key 两种方式Codex 主要是 API key 和 ChatGPT 登录。如果你在同一个环境里同时配置了多种认证工具可能会优先选择其中一个导致另一个失效。我踩过的坑是之前用 Claude Code 的订阅登录后来为了接本地模型加了ANTHROPIC_API_KEY环境变量结果 Claude Code 优先用了 API key但那个 key 是给本地模型用的官方端点不认于是报 “organization has disabled claude subscription access”。解决办法是在 openrig 的 profile 里明确指定认证方式启动本地模型 profile 时把订阅相关的环境变量清掉启动官方 profile 时把 API key 清掉。Codex 的登录问题也类似。如果之前登录过 ChatGPT 账号后来又配了 API key可能会出现登录态和 API key 冲突的情况。Codex 的配置文件里通常有auth_mode之类的字段明确设成apikey或chatgpt可以避免歧义。5.3 环境变量污染与会话恢复tmux 会话恢复后环境变量丢失或错乱是我遇到最多的问题之一。tmux 的session-created钩子只在新建会话时触发client-attached在重新连接时触发但如果你是用tmux attach恢复一个已经存在的会话钩子的行为可能跟预期不一样。更稳妥的做法是在 shell 的启动脚本里做判断检测当前是否在 tmux 里如果是就调用 openrig 的刷新命令。另一个容易忽略的点是环境变量的继承顺序。tmux 服务端启动时继承的是当时的环境变量之后新建的 pane 会继承服务端的环境。如果你在 tmux 服务端启动之后才改了 openrig 的配置新建 pane 里可能还是旧的环境。解决办法是用tmux set-environment显式更新 tmux 服务端的环境变量或者干脆重启 tmux 服务端。注意tmux set-environment只影响之后新建的 pane已经存在的 pane 不会自动更新。如果需要在现有 pane 里生效还是要手动执行 openrig 的刷新命令。5.4 模型响应超时与重试策略本地模型推理速度受硬件限制有时候响应会比较慢。Claude Code 和 Codex 默认的超时时间可能不够用导致请求被中断。openrig 如果支持超时配置可以在 profile 里加profiles: claude-local: tool: claude model: local-qwen endpoint: http://localhost:1234 api_key: local-key config_dir: ~/.openrig/profiles/claude-local timeout: 120000 retry: 2timeout单位是毫秒retry是失败重试次数。对于本地模型我一般把超时设到 120 秒以上重试 1 到 2 次。但重试也要小心如果模型服务本身已经过载重试只会加重负担。更好的做法是监控模型服务的负载在负载高的时候主动降低请求频率。如果遇到 “codex is ignoring 1 unrecognized configuration setting” 这类警告说明配置文件里有 Codex 不认识的字段。虽然只是警告不影响运行但最好还是清理掉避免以后升级版本时出问题。用openrig validate命令可以检查配置文件的合法性提前发现这类问题。6. 进阶用法与个人经验沉淀6.1 多项目配置档的目录级自动切换我手头同时维护着好几个项目每个项目用的 AI 助手和模型配置都不一样。如果每次切换项目都要手动改 openrig 配置那太麻烦了。我的做法是在每个项目根目录下放一个.openrig.yaml里面只写这个项目特有的覆盖项比如用哪个 profile、有没有特殊的模型参数。openrig 启动时从当前目录往上找最近的.openrig.yaml跟全局配置合并。这样在不同项目目录下打开 tmuxopenrig 会自动加载对应的配置不需要手动干预。合并逻辑是项目级配置覆盖全局配置的同名项模型定义和 profile 定义可以增量添加。这个方案的关键是 openrig 要支持配置继承和合并如果项目本身不支持可以通过包装脚本自己实现。6.2 用 openrig 管理 API 密钥的安全实践API 密钥不能明文写在配置文件里这是基本的安全常识。openrig 如果支持从环境变量或密钥管理服务读取密钥优先用那种方式。我的做法是把密钥放在~/.openrig/secrets.env里权限设成 600然后在 openrig 配置里用${ENV_VAR}的方式引用。启动时 openrig 会从环境里读取对应的值。# ~/.openrig/secrets.env LOCAL_MODEL_KEYsk-xxxx OFFICIAL_API_KEYsk-yyyyprofiles: claude-local: api_key: ${LOCAL_MODEL_KEY}这样配置文件可以安全地提交到 git密钥文件单独管理。如果团队协作每个人维护自己的 secrets 文件配置文件共享。6.3 性能调优与资源占用控制同时跑多个 AI 助手和本地模型对机器资源是个考验。我的经验是本地模型服务单独跑在一个进程里不要跟 AI 助手混在同一个 Node 进程里否则内存占用会很高。openrig 作为编排层本身不应该占用太多资源它的主要开销在代理转发和配置管理上。如果发现 openrig 启动慢检查它是否在启动时做了不必要的网络请求。配置加载应该是纯本地的模型连通性测试可以异步做或者按需做。tmux 钩子里的 openrig 命令要尽量轻量避免阻塞会话创建。对于本地模型显存是瓶颈。7B 模型量化后大概需要 6-8GB 显存13B 需要 10-12GB再大就需要多卡或者量化程度更高的版本。在 openrig 配置里根据实际硬件选择合适的模型不要盲目追求大参数。我实测下来7B 的代码模型在补全和简单重构任务上已经够用复杂推理还是得靠云端模型。6.4 后续可以扩展的方向openrig 目前主要解决的是配置编排和代理转发还有一些方向可以继续挖。比如跟 CI/CD 流程结合在自动化测试环节调用 AI 助手做代码审查或者跟编辑器插件联动在 VS Code 里通过 openrig 切换不同的模型后端再或者做一个简单的 Web 界面可视化管理和切换配置档。我个人比较期待的是 openrig 能支持配置档的版本管理和回滚。有时候改了一个参数导致工具不能用想回到之前的配置却记不清改了哪些。如果 openrig 能自动保存配置变更历史一键回滚会省很多事。另外就是多机同步在公司和家里的机器上用同一套配置通过 git 或者对象存储同步不用手动复制。这些扩展不一定都要等官方实现有些可以通过包装脚本自己搞定。关键是理解 openrig 的核心抽象——profile 和 model 的分离、配置目录的隔离、代理层的格式转换——在这个基础上做二次开发会容易很多。