openrig 编排 Claude Code 与 Codex：多模型接入与 tmux 会话管理实战

1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架项目毕竟 rig 在英文里有“装配、支架”的意思。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编程助手就会明白它出现的语境——这是一套围绕终端 AI 编码工具做统一编排、会话管理和多模型接入的工程化方案。简单说openrig 想干的事情是把你散落在 tmux 会话、多个 CLI 工具、多个模型供应商之间的工作流收拢成一套可复用、可切换、可观测的“装备架”。我接触它的契机很实际手上同时跑着 Claude Code 和 Codex一个负责大段重构一个负责快速补全和命令执行结果就是终端窗口开了七八个tmux 会话切来切去模型配置散落在各个配置文件里改一个 API 端点要翻三个地方。openrig 这类工具的核心价值就是把这些碎片化的东西统一起来让你在一个入口里管理会话、切换模型、复用配置。它适合谁三类人最该关注。第一类是已经在用 Claude Code 或 Codex 的开发者尤其是那种“两个都想用、又不想来回切环境”的人。第二类是想接入本地模型或第三方 API 的玩家比如把 Claude Code 指向 LM Studio 的本地模型或者让 Codex 走 DeepSeek、Qwen、GLM 这类兼容端点。第三类是团队里负责工程效率的人需要把 AI 编码工具的配置标准化让新人 clone 下来就能跑。需要先明确一点openrig 本身不是一个模型也不是一个 IDE 插件它更像是一层“编排壳”。它依赖 Node.js 运行时依赖 tmux 做会话持久化依赖各个 CLI 工具本身的安装。所以理解 openrig本质上要理解它背后这一整套工具链怎么协同。下面我会从整体设计、核心细节、实操落地、问题排查四个层面把这条链路彻底讲透。2. 整体设计与思路拆解为什么是这套组合2.1 为什么用 tmux 做会话底座终端 AI 工具最大的痛点之一是“会话易失”。你让 Claude Code 读了一整个代码库的上下文聊到一半关掉终端上下文就没了。Codex 执行长任务时同理进程一断前面的推理全白费。tmux 在这里扮演的角色是一个“会话容器”——它把进程和终端窗口解耦窗口关了进程还在后台跑下次 attach 回去上下文原样还在。openrig 选择 tmux 而不是自己实现一套会话管理是很务实的决定。自己造会话管理要处理 PTY、信号、断线重连、日志回放工作量巨大且容易出 bug。tmux 已经把这些打磨了十几年稳定性和跨平台性都经过验证。你只需要约定好会话命名规范比如openrig-claude-project、openrig-codex-project就能用脚本批量创建、切换、销毁会话。这里有个设计上的取舍值得说tmux 的会话是“进程级”的不是“应用级”的。也就是说openrig 管的是 tmux 会话会话里跑什么由你决定。这种松耦合的好处是灵活坏处是需要你自己保证会话里启动的命令正确。我见过有人把会话建好了结果里面跑的是个空 shellattach 进去一脸懵。所以 openrig 的脚本里通常会封装“创建会话并立即执行指定命令”的逻辑避免这种空会话问题。2.2 Node.js 在链路里的真实角色热词里反复出现 node.js 安装、node.js 官网下载、node.js LTS 下载这不是偶然。Claude Code 和 Codex 的 CLI 都是 Node.js 生态的产物通过 npm 全局安装。openrig 作为编排层大概率也是 Node.js 写的或者至少用 Node.js 脚本来做配置生成和进程调度。Node.js 在这里承担三件事第一是提供 CLI 运行环境没有它 Claude Code 和 Codex 根本装不上第二是作为脚本语言做配置文件的读写和模板渲染第三是充当本地代理层比如热词里提到的 “cc switch local proxy failed while handling codex endpoint /responses”这说明存在一个本地代理在转发请求而代理很可能就是 Node.js 起的 HTTP 服务。版本选择上我强烈建议用 LTS 版本而不是追最新的 Current 版本。热词里有个报错很典型“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”这就是版本号写错或者源里没有对应版本导致的。生产环境用 LTS比如 20.x 或 22.x兼容性最稳。Ubuntu 上装 Node.js 20 最省心的方式是用 NodeSource 的源而不是系统自带的 apt 版本系统自带的往往太旧。2.3 多模型接入的架构逻辑openrig 真正有意思的地方是它要同时伺候 Claude Code 和 Codex 两个“主子”还要让它们能接不同的模型后端。Claude Code 原生走 Anthropic 的接口Codex 原生走 OpenAI 的接口但社区需求是能不能让 Claude Code 调本地模型能不能让 Codex 接 DeepSeek这就引出了“兼容层”的设计。大多数第三方模型服务DeepSeek、Qwen、GLM、LM Studio提供的是 OpenAI 兼容接口也就是/v1/chat/completions那套。Claude Code 要接这些就需要一个转换层把 Anthropic 格式的请求转成 OpenAI 格式。热词里的 “cc switch” 和 “local proxy” 就是干这个的。openrig 的思路是把这些代理配置统一管理切换模型时只改一处配置而不是每个工具改一遍。架构上可以这样理解底层是模型服务官方 API 或本地服务中间是代理/转换层Node.js 服务上层是 CLI 工具Claude Code、Codex最外层是 openrig 的编排脚本和 tmux 会话。每一层职责清晰出问题时也容易定位是哪一层挂了。3. 核心细节解析与实操要点3.1 环境准备Node.js 与 tmux 的正确装法先说 Node.js。Ubuntu 上我踩过的坑是直接用apt install nodejs装出来是 12.x 甚至更老Claude Code 直接报引擎不兼容。正确做法是加 NodeSource 源curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完验证node -v和npm -v。如果公司网络受限也可以从 node.js 官网下载 LTS 的二进制包手动解压配好 PATH 一样能用。Windows 用户直接下官网的 LTS 安装包勾选“Add to PATH”装完重开终端。tmux 的安装简单sudo apt install tmux即可。但配置有讲究。默认的 tmux 前缀键是 Ctrlb和很多终端快捷键冲突我一般改成 Ctrla。另外要开鼠标支持不然滚动查看历史输出很痛苦。在~/.tmux.conf里加set -g mouse on set -g history-limit 50000 set -g base-index 1history-limit 调大很重要AI 工具输出动辄几千行默认 2000 行根本不够翻。base-index 从 1 开始是为了和键盘上的数字键对应符合直觉。注意改完 tmux 配置要tmux kill-server重启服务才生效或者新开会话。已经存在的会话不会自动加载新配置。3.2 Claude Code 与 Codex 的安装差异Claude Code 的安装官方推荐 npm 全局装npm install -g anthropic-ai/claude-code装完在项目目录下直接敲claude就能启动。第一次启动会引导你登录走浏览器授权。这里有个常见坑热词里 “your organization has disabled claude subscription access for claude code” 这个报错意思是你的账号所属组织禁用了 Claude Code 的订阅访问。这种情况要么换个人账号要么让管理员在组织设置里放开权限不是本地配置能解决的。Codex 的安装类似也是 npm 全局装。但 Codex 的登录和配置更复杂一些热词里 “codex登录不上”、“codex无法加载组织设置” 都是高频问题。Codex 登录走的是 OpenAI 的账号体系如果账号本身没有 Codex 权限或者所在组织限制了就会卡在登录环节。我的经验是先用官方账号在网页端确认能正常访问再回来配 CLI。两者的配置目录不同。Claude Code 的配置一般在~/.claude/下Codex 在~/.codex/下。openrig 要做的是把这两个目录的关键配置项抽象出来用统一的模板生成。比如模型端点、API Key、超时时间这些定义一份 openrig 的配置然后渲染到各自的配置文件里。3.3 本地代理与模型切换的关键参数让 Claude Code 调本地模型核心是设置环境变量指向代理地址。以 LM Studio 为例它默认在http://localhost:1234/v1提供 OpenAI 兼容接口。你需要一个转换代理把 Claude Code 的请求转过去。代理启动后设置export ANTHROPIC_BASE_URLhttp://localhost:8080 export ANTHROPIC_API_KEYdummy-key这里的 8080 是代理监听端口dummy-key 是因为本地模型不校验 key但 Claude Code 要求必须有一个非空值。代理内部再把 Anthropic 格式转成 OpenAI 格式发给 LM Studio。Codex 接 DeepSeek 类似DeepSeek 提供 OpenAI 兼容接口所以 Codex 可以直接配 base_url 指向 DeepSeek 的端点不需要额外转换层。但要注意模型名映射热词里 “the gpt-5.6-sol model is not supported when using codex with a...” 这种报错就是模型名写错了或者该端点不支持这个模型。配置时务必用服务商文档里给出的准确模型名。工具原生接口接第三方方式关键配置项Claude CodeAnthropic需转换代理ANTHROPIC_BASE_URLCodexOpenAI可直接兼容base_url modelLM StudioOpenAI 兼容直接可用localhost:1234/v1DeepSeekOpenAI 兼容直接可用api.deepseek.com提示切换模型后一定要新开会话测试旧会话可能缓存了之前的模型配置导致你以为切换没生效。4. 实操过程与核心环节实现4.1 从零搭建 openrig 工作流的完整步骤假设你在一台干净的 Ubuntu 机器上要从零把 openrig 这套工作流跑起来我按实际顺序拆一遍。第一步装基础依赖。Node.js 20 LTS、tmux、git 三样先到位。验证命令node -v输出 v20.xtmux -V输出 3.xgit --version正常。第二步装 CLI 工具。npm install -g anthropic-ai/claude-code然后装 Codex。装完分别跑一次claude --version和 codex 的版本命令确认可执行文件在 PATH 里。如果提示 command not found多半是 npm 全局 bin 目录没进 PATH用npm config get prefix看路径把它加到 PATH。第三步配置 tmux。写好~/.tmux.conf重点是鼠标、历史行数、前缀键。然后写一个 openrig 的会话启动脚本比如openrig-start.sh#!/bin/bash PROJECT$1 SESSIONopenrig-$PROJECT tmux new-session -d -s $SESSION -c $(pwd) tmux send-keys -t $SESSION claude C-m echo Session $SESSION started这个脚本做了三件事用项目名建会话、把工作目录设成当前目录、在会话里自动启动 claude。这样你./openrig-start.sh myproject就能一键起一个带上下文的 Claude Code 会话。第四步配置模型接入。如果要接本地模型先起 LM Studio 加载模型确认http://localhost:1234/v1/models能返回模型列表。然后起转换代理设置环境变量。这一步最容易出问题的是端口冲突和代理没起来建议用curl先测代理的健康检查端点。第五步验证端到端。在 tmux 会话里让 Claude Code 执行一个简单任务比如“读一下当前目录的 README 并总结”。如果它能正常返回说明整条链路通了。如果报连接错误按“模型服务 → 代理 → CLI 配置”的顺序逐层排查。4.2 会话管理与多项目并行的实操技巧openrig 的会话命名规范直接决定了你后续管理的效率。我的命名习惯是openrig-工具-项目-用途比如openrig-claude-webapp-refactor、openrig-codex-api-debug。这样tmux ls一眼就能看出每个会话在干嘛。多项目并行时tmux 的窗口和面板要善用。一个会话里可以开多个窗口一个窗口可以切多个面板。我通常一个项目一个会话会话里第一个窗口跑 Claude Code第二个窗口跑 Codex第三个窗口留给 shell 做 git 操作和测试。切换用Ctrla加数字键比开一堆终端标签页清爽得多。会话持久化是 tmux 最大的价值。下班前不用关会话直接 detachCtrla d第二天 attach 回来AI 的上下文、终端的历史输出全在。机器重启后 tmux 会话会丢这时候可以用 tmux-resurrect 这类插件做会话快照和恢复但要注意它恢复的是会话结构不恢复进程内存AI 的上下文还是得重新建立。注意tmux 会话里的进程如果被 CtrlC 中断会话本身还在但进程没了。重新跑命令即可不用重建会话。4.3 配置文件模板化的落地方法openrig 真正提升效率的地方是把配置模板化。我一般维护一个~/.openrig/templates/目录里面放 Claude Code 和 Codex 的配置模板用环境变量占位。比如 Claude Code 的模板{ model: ${OPENRIG_MODEL}, baseUrl: ${OPENRIG_BASE_URL}, apiKey: ${OPENRIG_API_KEY}, timeout: 120000 }然后写一个渲染脚本读取当前 openrig 的 profile比如local、deepseek、official把对应变量注入模板输出到实际的配置路径。切换 profile 就是改一个环境变量或者跑一个切换命令所有工具的配置一次性更新。这套做法的好处是配置集中、可版本控制、可分享。团队里新人 clone 下来跑一次初始化脚本填上自己的 API Key就能得到和老人一致的环境。坏处是模板和实际配置之间多了一层调试时要记得看渲染后的实际文件而不是只看模板。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解法安装阶段最高频的问题集中在 Node.js 版本和 npm 权限上。热词里 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这类报错本质是版本号不存在或者源里没有。解法很简单去 node.js 官网看当前 LTS 的确切版本号别凭记忆写。Ubuntu 上用 NodeSource 源时setup 脚本里的版本号也要和实际发布的对应。npm 全局安装报 EACCES 权限错误是因为全局目录归 root 所有。别用sudo npm install -g那样会把文件属主搞乱。正确做法是配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH然后重新装就不会有权限问题了。这个 PATH 要写进~/.bashrc或~/.zshrc否则新终端里找不到命令。Codex 安装后 “is ignoring 1 unrecognized configuration setting” 这个警告意思是配置文件里有个它不认识的键。不影响运行但说明你的配置模板和当前 Codex 版本不匹配。解法是对照官方文档的配置项清单把废弃的键删掉。这种警告别忽视积累多了容易掩盖真正的问题。5.2 登录与权限类问题的排查路径“codex登录不上”、“codex无法加载组织设置”、“your organization has disabled claude subscription access” 这一类本质都是账号权限问题不是本地环境问题。排查路径是先在浏览器里用同一账号登录服务商网页端确认账号本身正常、有对应产品的访问权限。如果网页端都不行CLI 端再怎么折腾也没用。如果网页端正常但 CLI 登录失败检查网络是否能正常访问服务商的 API 域名。有些企业网络会拦截特定域名表现就是登录请求超时。这种情况需要联系网络管理员放行或者换网络环境测试。组织设置加载失败常见于账号同时属于多个组织CLI 不知道该用哪个。解法是在配置里显式指定组织 ID或者退出多余的组织。这个信息一般在服务商账号设置页面能找到。5.3 模型调用失败的速查表模型调用环节的问题最杂我整理了一张速查表按报错现象反查原因报错现象可能原因排查动作local proxy failed代理未启动或端口占用检查代理进程和端口model is not supported模型名错误或端点不支持核对服务商模型名连接超时网络不通或端点地址错curl 测试端点连通性401 未授权API Key 错误或过期重新生成 Key返回空响应模型未加载或参数不兼容检查模型服务日志“cc switch local proxy failed while handling codex endpoint /responses” 这个报错特别典型它说明代理在处理 Codex 的/responses端点时挂了。Codex 用的不是标准的/chat/completions而是/responses如果你的转换代理只实现了前者就会失败。解法是确认代理支持 Codex 的端点格式或者换一个兼容性更好的代理实现。提示排查模型问题时养成“先 curl 端点、再看代理日志、最后看 CLI 输出”的习惯能省掉大量瞎猜的时间。5.4 我踩过的几个真实坑第一个坑是 tmux 会话里的环境变量不继承。我在 shell 里 export 了 ANTHROPIC_BASE_URL然后新建 tmux 会话结果会话里读不到这个变量。原因是 tmux 服务端启动时捕获的是当时的环境后续 shell 里改的不影响已运行的 tmux 服务。解法是把环境变量写进 tmux 配置或者启动脚本里别依赖交互式 shell 的 export。第二个坑是代理端口和模型服务端口冲突。LM Studio 默认 1234我的代理也想用 1234结果代理起不来还不报明显错误。后来统一规划端口模型服务 1234转换代理 8080管理接口 9090写进文档再也不冲突。第三个坑是配置文件编码问题。Windows 上编辑的配置文件带到 Linux 上带了 BOM 头Node.js 解析 JSON 直接报错。解法是统一用 UTF-8 无 BOM 保存或者用dos2unix处理一下。这种问题很隐蔽报错信息也不直观但一旦遇到一次就记住了。第四个坑是模型切换后没清缓存。Claude Code 有些版本会缓存模型列表切换端点后不重启会话它还在用旧的模型信息。表现就是明明配了新模型调用还是走老的。解法是切换配置后强制新开会话别在旧会话里试。6. 进阶玩法与效率提升思路6.1 把 openrig 做成团队标准环境一个人用 openrig 是提效一个团队用就是标准化。我的做法是把 openrig 的配置模板、启动脚本、tmux 配置打包成一个 git 仓库新人入职 clone 下来跑一个./setup.sh脚本自动检测依赖、装 Node.js、装 CLI 工具、渲染配置模板、建好 tmux 会话。整个过程十分钟内完成比口头教一遍靠谱得多。仓库里要包含一份README写清楚每个 profile 对应什么模型、需要哪些 API Key、常见问题怎么解。API Key 绝对不能进仓库用.env.example做占位实际 Key 让每个人自己填。这样既保证了配置一致性又不会泄露凭证。6.2 用脚本自动化重复操作openrig 的日常操作里有很多可以脚本化的地方。比如“新建项目会话并启动 Claude Code”可以封装成一个命令“切换模型 profile”可以封装成一个命令“查看所有 openrig 会话状态”也可以封装。我习惯把这些脚本放在~/.openrig/bin/下加进 PATH用起来就像系统命令一样。一个实用的脚本是“会话健康检查”遍历所有 openrig 开头的 tmux 会话检查里面的进程是否还活着把死掉的会话清理掉。AI 工具跑久了偶尔会崩留着死会话占资源还容易混淆。定期跑一下清理脚本环境始终干净。6.3 监控与日志的轻量方案openrig 跑起来后你需要知道每个会话在干嘛、有没有报错。最轻量的方案是 tmux 的capture-pane命令可以把指定会话的当前输出抓出来存成文件。写个定时脚本每隔几分钟抓一次出问题时翻日志就有据可查。再进一步可以把关键事件会话创建、模型切换、错误发生写到一个统一的日志文件里带时间戳。这样排查问题时时间线一目了然。不用上什么重型监控系统一个 append 模式的日志文件加tail -f就够了。AI 编码工具的使用场景轻量方案往往比复杂方案更实用。我个人在实际操作中的体会是openrig 这类编排工具的价值不在于它本身多复杂而在于它把一堆零散的工具和配置收拢成了一个可重复、可分享、可排查的整体。你花在搭建上的时间会在后续每一次切换模型、每一个新项目、每一次团队协作里赚回来。最后分享一个小技巧把最常用的三个操作起会话、切模型、看状态做成最短的命令别名肌肉记忆一旦形成整套工作流的流畅度会有质的提升。