★ FEATURED ARTICLE 1. 从 openrig 说起一个把 Claude Code 和 Codex 装进 tmux 的编排器第一次看到openrig这个名字我下意识把它拆成了 open rig——rig 在工程语境里就是装配台、机架的意思把一堆零散的工具、模型、会话像搭机架一样组装起来。这个理解基本没错。openrig 要解决的核心问题非常具体当你同时用 Claude Code 和 Codex 这两个终端里的 AI 编程助手时怎么让它们在一个可控、可复用、可切换的环境里跑起来而不是每次开新终端、重新配环境变量、重新登录、重新切模型。我自己的日常是这样的白天用 Claude Code 处理重构和长上下文理解晚上用 Codex 跑一些批量代码生成和脚本任务中间还要在本地模型比如通过 LM Studio 起的服务和云端 API 之间来回切。以前的做法是开一堆终端窗口每个窗口一套环境变量切来切去经常搞混ANTHROPIC_BASE_URL和OPENAI_BASE_URL混着设最后报一堆莫名其妙的错。openrig 这类工具的价值就在于它把会话管理这件事从手动开终端升级成了声明式编排。它适合谁三类人最该关注。第一类是同时使用 Claude Code 和 Codex 的重度用户尤其是需要在多个项目、多个模型后端之间切换的人第二类是想把 AI 编程助手接入本地模型LM Studio、Ollama 之类的折腾党第三类是需要把 AI 助手跑在远程服务器上、通过 tmux 保持长会话的运维型开发者。如果你只是偶尔用一下 Claude Code 写个函数那 openrig 对你来说可能有点重但只要你开始认真把 AI 助手当成日常生产力工具会话编排这件事迟早会找上你。下面我会从整体设计思路、核心组件拆解、实操落地、问题排查四个层面把 openrig 这类编排器的完整逻辑讲清楚。中间会大量涉及 Node.js 环境、tmux 会话、Claude Code 与 Codex 的配置差异、本地模型接入这些实操细节都是我踩过坑之后总结出来的。2. 整体设计思路为什么是 tmux Node.js 多后端切换2.1 为什么编排层要选 tmux 而不是自己写进程管理很多人第一反应是我直接用 Node.js 的child_process起子进程不就行了为什么要套一层 tmux这个问题我认真想过也两种方案都试过结论是 tmux 在长会话 可附着 可观测这三个维度上几乎无可替代。用child_process.spawn起 Claude Code进程是挂在你的 Node 主进程下面的。一旦主进程崩了、终端关了、SSH 断了子进程跟着一起没。而 AI 编程助手最典型的使用场景恰恰是长任务——让它读几十个文件、跑一轮重构、生成一批测试这些动辄几分钟到几十分钟。中途断掉重来上下文全丢非常痛苦。tmux 解决的就是这个会话与终端解耦的问题。tmux 会话跑在后台的 server 进程里你的终端只是附着上去看它。关掉终端、断掉 SSH会话照样活着下次tmux attach回来Claude Code 还在原地等你。这一点对于把 AI 助手跑在远程开发机上的场景是刚需。另外 tmux 天然提供了多窗口、多面板的组织能力。你可以一个窗口跑 Claude Code一个窗口跑 Codex一个窗口跑日志监控一个窗口跑 git 状态。openrig 这类工具做的事情本质上是把这套 tmux 布局模板化、参数化让你一条命令就能拉起一整套预设好的工作台而不是每次手动tmux new -s然后一个个敲命令。提示tmux 的会话是独立于终端的但依赖于 tmux server 进程。如果服务器重启会话还是会丢。真正需要跨重启持久化的场景得配合 systemd 或者专门的会话保持方案这一点后面会讲。2.2 Node.js 在整条链路里扮演什么角色热词里node.js、node.js安装、node.js官网下载出现频率极高这不是偶然。Claude Code 和 Codex 的 CLI 版本本质上都是 Node.js 应用通过 npm 全局安装。所以 Node.js 是整个链路的地基地基没打好后面全是坑。Node.js 在这里的角色可以类比成运行 AI 助手的发动机。Claude Code 的 CLI 是一个 Node 包Codex 的 CLI 也是。它们需要 Node 运行时来执行需要 npm 来安装和更新需要正确的版本才能跑起来。我见过太多人卡在第一步Node 版本不对装 Claude Code 直接报错或者装上了但运行时报一堆模块找不到。关于版本选择我的建议很明确用 LTS 版本不要追最新版。热词里有一条error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这就是典型的版本号写错或版本还没发布导致的安装失败。Node.js 的版本号是有严格语义的偶数大版本是 LTS长期支持奇数大版本是 Current尝鲜。生产环境、日常开发环境一律选 LTS。截至我写这篇的时候Node 20 和 Node 22 的 LTS 都是稳妥选择。版本管理上我强烈建议用nvmNode Version Manager而不是直接装系统级 Node。原因很简单不同项目可能依赖不同 Node 版本系统级 Node 只能有一个版本切换起来极其痛苦。nvm 让你可以nvm install 20、nvm use 20随时切而且不会污染系统环境。Windows 用户可以用nvm-windows功能基本对齐。2.3 多后端切换Claude Code 与 Codex 的配置差异这是 openrig 最核心的价值点也是最容易踩坑的地方。Claude Code 和 Codex 虽然都是 AI 编程助手但它们的配置体系完全不同。Claude Code 走的是 Anthropic 的 API 体系核心环境变量是ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL。如果你想让它调用本地模型或者第三方兼容端点就是改ANTHROPIC_BASE_URL指向你的服务地址。Codex 走的是 OpenAI 体系核心是OPENAI_API_KEY和OPENAI_BASE_URL。两套变量名不一样但逻辑是对称的。问题在于很多人想用同一个后端比如 DeepSeek、Qwen、GLM 这些兼容 OpenAI 协议的服务同时喂给两个工具。这时候就需要做协议适配——Claude Code 期望的是 Anthropic 格式的请求Codex 期望的是 OpenAI 格式的请求。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错本质就是代理层在转发 Codex 的/responses端点时出了问题可能是路径没对上也可能是请求体格式没转换。openrig 这类编排器的设计思路就是把这些后端定义抽象成配置文件。你声明几个后端比如anthropic-official、deepseek、local-lmstudio每个后端定义好 base_url、api_key、协议类型然后在启动会话时指定用哪个后端。切换后端不需要改环境变量、不需要重启终端只需要在编排层换个参数。维度Claude CodeCodexAPI 协议Anthropic MessagesOpenAI Chat/Responses核心环境变量ANTHROPIC_API_KEY / ANTHROPIC_BASE_URLOPENAI_API_KEY / OPENAI_BASE_URL本地模型接入需 Anthropic 兼容代理需 OpenAI 兼容端点典型报错组织订阅权限、地区限制组织设置加载失败、配置项拼写这张表是我实际配置时总结的建议直接存下来。每次配新后端先对照这张表确认变量名和协议类型能省掉一大半排查时间。3. 核心组件拆解与实操要点3.1 Node.js 环境搭建从下载到验证的完整链路环境搭建这一步我见过太多人栽跟头所以这里讲细一点。整个流程分四步装 nvm、装 Node LTS、验证版本、配置 npm 镜像可选但强烈建议。第一步装 nvm。Linux/macOS 下用官方脚本安装装完记得把 nvm 的初始化脚本加到 shell 配置里.bashrc或.zshrc否则新开终端 nvm 命令找不到。Windows 用户去 nvm-windows 的 release 页面下载安装包装完可能需要手动配置一下环境变量。第二步装 Node LTS。nvm install --lts会自动装最新的 LTS 版本。装完nvm use --lts切过去。如果你需要固定某个版本比如 20就nvm install 20。第三步验证。这一步千万别省。跑node -v和npm -v确认版本号符合预期。如果node -v报 command not found说明 PATH 没配好回去检查 nvm 初始化。第四步npm 镜像。国内网络环境下npm 官方源拉包经常超时。配置一个国内镜像能显著提升安装成功率。npm config set registry https://registry.npmmirror.com一行搞定。这一步不是必须的但能省很多等待时间。注意不要用sudo npm install -g。用 sudo 装全局包会把包装到系统目录权限混乱后续升级和卸载都是灾难。nvm 管理的 Node 天然支持无 sudo 全局安装这也是用 nvm 的另一个理由。装完 Node就可以装 Claude Code 和 Codex 了。Claude Code 的安装命令是npm install -g anthropic-ai/claude-codeCodex 的安装命令类似具体包名以官方文档为准。装完各自跑一下--version确认能起来。3.2 tmux 会话编排布局、命名与持久化tmux 这块openrig 的核心思路是用脚本定义布局用命令拉起会话。我自己的做法是写一个 shell 脚本里面用tmux new-session -d -s 会话名创建后台会话然后用tmux send-keys往各个窗口发送启动命令。一个典型的三窗口布局是这样的窗口 0 跑 Claude Code窗口 1 跑 Codex窗口 2 跑一个 shell 用于 git 操作和日志查看。创建命令大致是tmux new-session -d -s aiwork -n claude tmux send-keys -t aiwork:claude claude C-m tmux new-window -t aiwork -n codex tmux send-keys -t aiwork:codex codex C-m tmux new-window -t aiwork -n shellC-m就是回车键send-keys把命令敲进对应窗口。这套逻辑你可以直接抄改改会话名和命令就行。会话命名上有个经验用项目名 用途做前缀比如projA-claude、projA-codex。这样tmux ls列出来一目了然不会一堆0、1、2分不清哪个是哪个。我早期就是随便命名结果开了七八个会话之后完全懵了只能一个个 attach 进去看效率极低。持久化方面tmux 会话本身不跨重启。如果你需要服务器重启后自动恢复会话得配合 systemd 写一个 service开机时执行你的编排脚本。这个属于进阶用法普通开发机用不上但远程开发机场景值得配。3.3 后端配置抽象把 API Key 和 Base URL 管起来后端配置这块我的核心原则是配置和代码分离敏感信息和配置分离。具体来说API Key 这类敏感信息绝对不要硬编码在脚本里也不建议直接写在 shell 的.bashrc里容易被误提交、误截图。推荐的做法是用一个独立的配置文件比如~/.config/openrig/backends.env权限设成 600只有自己能读。配置文件的内容大致长这样# anthropic 官方 BACKEND_anthropic_BASE_URLhttps://api.anthropic.com BACKEND_anthropic_API_KEYsk-ant-xxx BACKEND_anthropic_PROTOCOLanthropic # deepseekOpenAI 兼容 BACKEND_deepseek_BASE_URLhttps://api.deepseek.com/v1 BACKEND_deepseek_API_KEYsk-xxx BACKEND_deepseek_PROTOCOLopenai # 本地 LM Studio BACKEND_local_BASE_URLhttp://127.0.0.1:1234/v1 BACKEND_local_API_KEYnot-needed BACKEND_local_PROTOCOLopenai启动会话时编排脚本根据你指定的后端名把对应的变量 export 成 Claude Code 或 Codex 认识的名字。比如选了deepseek后端跑 Codex就 exportOPENAI_BASE_URL和OPENAI_API_KEY选了anthropic后端跑 Claude Code就 exportANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。这里有个关键细节协议类型决定要不要走代理。如果后端是 OpenAI 协议但你要喂给 Claude Code中间就需要一个协议转换代理把 Anthropic 格式的请求转成 OpenAI 格式。热词里cc switch local proxy failed这类报错十有八九是代理层配置不对。我的建议是能用原生协议就用原生协议Claude Code 配 Anthropic 兼容后端Codex 配 OpenAI 兼容后端少一层转换少一层坑。3.4 本地模型接入LM Studio 与兼容端点的实操本地模型接入是很多人折腾 openrig 的初衷。用 LM Studio 起一个本地服务然后让 Claude Code 或 Codex 调用好处是数据不出本机、不花钱、断网也能用。坏处是本地模型的能力和云端还有差距复杂任务容易翻车。LM Studio 的配置流程下载安装、在模型市场下载一个模型推荐 7B 到 14B 量级的指令微调模型太大跑不动太小不好用、在 Local Server 标签页启动服务、记下端口号默认 1234。启动后服务地址就是http://127.0.0.1:1234/v1这是 OpenAI 兼容格式。然后把这个地址配成 Codex 的后端OPENAI_BASE_URLhttp://127.0.0.1:1234/v1OPENAI_API_KEY随便填一个非空值LM Studio 不校验。Codex 就能调用本地模型了。Claude Code 接本地模型要麻烦一点因为 LM Studio 提供的是 OpenAI 格式Claude Code 要的是 Anthropic 格式。你需要一个转换代理。这类代理工具有不少开源实现核心逻辑就是把/v1/messages的请求体转成/v1/chat/completions的格式再把响应转回去。配置代理时要注意路径映射和字段映射尤其是system字段、messages结构、max_tokens这些两边格式不完全一样。提示本地模型跑 Claude Code 时上下文长度是个硬约束。Claude Code 的很多操作会塞入大量文件内容本地模型如果上下文窗口只有 4K 或 8K很容易爆。建议至少选 32K 上下文的模型体验会好很多。4. 完整实操流程从零拉起一套 AI 编程工作台4.1 环境准备清单与安装顺序我把整个流程的依赖关系理了一遍正确的安装顺序是这样的先装 nvm再装 Node LTS再装 tmux再装 Claude Code 和 Codex最后配后端和编排脚本。顺序错了会出现命令找不到之类的低级问题。步骤操作验证命令常见问题1安装 nvmnvm --versionshell 配置未加载2安装 Node LTSnode -v版本非 LTS3安装 tmuxtmux -V包管理器源问题4安装 Claude Codeclaude --versionnpm 权限、网络超时5安装 Codexcodex --version包名错误6配置后端手动测试 APIKey 无效、Base URL 错7编写编排脚本运行脚本会话名冲突这张表建议打印出来贴在显示器边上装环境的时候一项项打勾。我装第一台开发机的时候就是没按顺序来先装了 Claude Code 才发现 Node 版本不对卸载重装折腾了半小时。4.2 编排脚本的编写与参数设计编排脚本是整个 openrig 的核心。我写了一个简化版逻辑清晰你可以直接改。核心参数有三个会话名、后端名、要启动的工具列表。#!/usr/bin/env bash set -euo pipefail SESSION${1:-aiwork} BACKEND${2:-anthropic} CONFIG$HOME/.config/openrig/backends.env # 加载后端配置 source $CONFIG # 读取对应后端的变量 BASE_URL_VARBACKEND_${BACKEND}_BASE_URL API_KEY_VARBACKEND_${BACKEND}_API_KEY PROTOCOL_VARBACKEND_${BACKEND}_PROTOCOL BASE_URL${!BASE_URL_VAR} API_KEY${!API_KEY_VAR} PROTOCOL${!PROTOCOL_VAR} # 根据协议导出对应环境变量 if [ $PROTOCOL anthropic ]; then export ANTHROPIC_BASE_URL$BASE_URL export ANTHROPIC_API_KEY$API_KEY else export OPENAI_BASE_URL$BASE_URL export OPENAI_API_KEY$API_KEY fi # 创建 tmux 会话 tmux new-session -d -s $SESSION -n claude tmux send-keys -t $SESSION:claude claude C-m tmux new-window -t $SESSION -n codex tmux send-keys -t $SESSION:codex codex C-m tmux new-window -t $SESSION -n shell tmux attach -t $SESSION这个脚本里用了 bash 的间接变量引用${!VAR}这是根据后端名动态取变量的关键技巧。set -euo pipefail是防御性编程任何一步出错就停避免带着错误状态继续跑。参数设计上会话名默认aiwork后端名默认anthropic。你可以./openrig.sh projA deepseek这样调用给项目 A 起一个用 DeepSeek 后端的会话。这种位置参数 默认值的设计兼顾了简单场景和灵活场景。4.3 启动、切换与关闭的日常操作脚本写好后日常操作就三件事启动、切换、关闭。启动就是跑脚本./openrig.sh或者加参数。脚本会自动创建会话、拉起工具、attach 进去。你看到的就是一个分好窗口的 tmux 界面Claude Code 和 Codex 各占一个窗口。切换分两种。一种是在 tmux 内部切窗口Ctrl-b然后按窗口号或者Ctrl-b n切下一个。另一种是切换后端这个需要退出当前会话、用新后端重新起一个。因为环境变量是在会话创建时注入的运行中改不了。如果你需要频繁切后端可以同时起多个会话每个会话一个后端用tmux ls和tmux attach -t 名字在会话间跳。关闭会话用tmux kill-session -t 名字。如果只是想 detach 不关闭Ctrl-b d就行会话继续在后台跑。我一般下班前 detach第二天 attach 回来Claude Code 的上下文还在接着干。注意detach 之前确认一下有没有正在跑的长任务。虽然 detach 不会中断任务但如果你误以为关了终端任务就停了可能会重复触发。养成习惯detach 前看一眼各窗口状态。4.4 与 VS Code 的协同终端内外的分工热词里vscode配置claude code、claude code for vs code、vscode接入claude code出现很多次说明很多人是在 VS Code 里用 Claude Code 的。这里要理清一个关系Claude Code 有 CLI 版也有 VS Code 扩展版。两者可以共存但用途不同。VS Code 扩展版的优势是深度集成编辑器能直接读取当前打开的文件、选区、诊断信息交互更顺滑。CLI 版的优势是灵活、可编排、可跑在 tmux 里、可远程。我的用法是日常小改动用 VS Code 扩展大重构、批量任务、远程开发用 tmux 里的 CLI 版。两者共享同一套后端配置吗不一定。VS Code 扩展通常有自己的设置界面配置存在 VS Code 的 settings.json 里。CLI 版读的是环境变量。所以你可能需要在两个地方各配一遍。我的建议是把后端信息集中管理VS Code 那边通过${env:VAR}引用环境变量这样改一处两边都生效。VS Code 的settings.json里可以这样写{ claude-code.apiKey: ${env:ANTHROPIC_API_KEY}, claude-code.baseUrl: ${env:ANTHROPIC_BASE_URL} }这样只要你启动 VS Code 的环境里有这两个变量扩展就能用。配合前面的编排脚本整个链路就打通了。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解决安装阶段最高频的报错热词里已经暴露了不少。我挑几个最典型的讲。error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava——这个报错的意思是你要装的 Node 版本号不存在或还没发布。Node 的版本号是主版本.次版本.修订号24.21.0 这种版本号如果官方还没发布nvm 就找不到。解决办法用nvm ls-remote --lts看一下当前可用的 LTS 版本装一个真实存在的。别凭记忆写版本号。your organization has disabled claude subscription access for claude code——这是账号层面的权限问题不是技术问题。通常是你的账号所属组织关闭了 Claude Code 的访问权限。解决办法是联系组织管理员或者换一个个人账号。这个报错跟 openrig 本身无关但很多人会误以为是配置问题白白折腾半天。note: claude code might not be available in your country——地区可用性提示。这个属于服务提供方的地区策略遇到就按官方指引处理不在技术排查范围内。codex is ignoring 1 unrecognized configuration setting. check for typos——Codex 的配置项拼写错误。Codex 对配置项名称是严格匹配的多一个字母少一个字母都会报这个。解决办法对照官方文档逐字核对配置项名称。我踩过一次把base_url写成了baseUrl排查了二十分钟。5.2 运行阶段的连接与代理问题运行阶段最烦的是连接问题。cc switch local proxy failed while handling codex endpoint /responses这个报错拆开看cc switch是切换工具local proxy是本地代理failed while handling codex endpoint /responses是处理 Codex 的/responses端点时失败。排查思路分三层。第一层确认代理服务本身起来了端口在监听。curl http://127.0.0.1:端口/health之类的健康检查端点试一下。第二层确认路径映射对。Codex 请求的是/responses你的代理有没有正确转发这个路径有些代理只处理/chat/completions遇到/responses就 404。第三层确认请求体格式。Codex 的/responses端点和/chat/completions端点请求体结构不同代理如果按老格式解析就会失败。codex无法加载组织设置这个报错通常是 Codex 启动时去拉组织配置失败了。可能是网络问题可能是 API Key 权限不够也可能是后端根本不支持组织配置这个接口。如果是接第三方兼容后端很多后端没有实现组织配置接口Codex 拉不到就报错。这种情况一般不影响核心功能可以忽略或者在配置里关掉组织配置的拉取。5.3 模型切换后的行为异常排查切换后端之后最容易出现的行为异常是模型不按预期工作。比如切到本地小模型后Claude Code 开始胡言乱语、工具调用格式错误、或者干脆不调用工具。这类问题的根因通常是模型能力与工具要求不匹配。Claude Code 和 Codex 都依赖模型具备较强的工具调用能力也就是按照特定格式输出函数调用请求。云端大模型这方面训练充分本地小模型经常不达标。表现就是模型输出了看似合理但格式错误的工具调用或者干脆用自然语言描述我应该调用某个工具而不实际调用。排查方法先看原始响应。在代理层加日志把模型返回的原始内容打出来。如果看到工具调用格式明显不对那就是模型能力问题换更大的模型或者换回云端。如果格式对但参数错可能是提示词或工具定义的问题。另一个常见异常是上下文超限。本地模型上下文窗口小Claude Code 塞入大量文件后直接超限模型要么报错要么截断。解决办法是减少单次操作涉及的文件数量或者换大上下文模型。报错/异常可能原因排查方向解决方式代理处理 /responses 失败路径未映射检查代理路由配置补上 /responses 路由组织设置加载失败后端不支持该接口抓包看请求忽略或关闭该功能配置项被忽略拼写错误逐字核对文档修正拼写模型工具调用异常模型能力不足看原始响应换更大模型上下文超限窗口太小看 token 计数减少文件或换模型这张表是我实际排查中积累的遇到问题先对号入座能快速定位方向。5.4 会话丢失与恢复的应对策略tmux 会话丢失是远程开发场景的高频问题。原因无非几种服务器重启、tmux server 被杀、磁盘满导致写入失败。预防措施第一重要会话定期 detach 而不是关闭让它常驻。第二服务器上配 systemd 服务开机自动重建会话。第三Claude Code 和 Codex 的重要上下文定期手动导出或记录关键信息别全指望会话活着。恢复措施如果会话没了重新跑编排脚本起一个。Claude Code 的对话历史通常存在本地某个目录重新启动后可能能恢复部分上下文但不要抱太大期望。我的经验是把重要的任务拆成小步每步完成就提交代码或记录结论这样即使会话丢了损失也可控。提示tmux 的resurrect和continuum这两个插件能实现会话的自动保存和恢复配置一下能省不少心。不过插件本身也有兼容性问题装之前先看 issue 区有没有跟你环境匹配的坑。6. 我踩过的坑和几条实在建议折腾 openrig 这类编排器大半年踩的坑够写一本小册子了。挑几条最有价值的分享。第一条别一上来就追求全自动。我最初想做一个一条命令搞定所有后端切换、会话管理、日志收集的超级脚本结果复杂度爆炸调试成本极高最后反而不好用。后来退回到脚本 手动微调的混合模式简单可靠。自动化是手段不是目的能省事就行别为了自动化而自动化。第二条环境变量是万恶之源但也是万能钥匙。Claude Code 和 Codex 的配置几乎全靠环境变量好处是灵活坏处是容易乱。我的做法是所有环境变量集中在一个配置文件里定义脚本负责按需导出绝不在多个地方散落定义。这样排查问题时只需要看一个文件。第三条本地模型适合特定任务别指望它全能。本地模型跑简单的代码补全、格式转换、单文件重构没问题但涉及跨文件理解、复杂工具调用链还是云端模型稳。我的分工是本地模型处理隐私敏感的小任务云端模型处理复杂的大任务。openrig 的价值就是让这个切换变得无感。第四条日志一定要留。代理层的请求日志、tmux 的会话日志、工具的报错日志全都留着。出问题的时候日志是唯一能告诉你到底发生了什么的东西。我现在的习惯是每个会话配一个日志窗口tail -f盯着关键日志出问题第一时间能看到。第五条版本锁定。Node 版本、Claude Code 版本、Codex 版本、代理工具版本全都记下来。某次升级之后突然不好用了回退到记录里的版本大概率能恢复。AI 工具迭代快新版本引入回归 bug 是常事有个已知可用版本清单能救命。这套东西搭起来之后我的日常效率确实上了一个台阶。以前切换项目要重新配环境、重新登录、重新开窗口现在一条命令拉起一整套工作台Claude Code 和 Codex 各就各位后端想换就换。如果你也在同时用这两个工具强烈建议花半天时间把 openrig 这类编排搭起来前期投入很快就能回本。
阅读完成 · 觉得有帮助？
