1. 从 openrig 说起一个把 Claude Code 和 Codex 装进 tmux 的编排器第一次看到openrig这个名字我下意识把它拆成了 open rig——rig 在工程语境里就是装配台、机架的意思把一堆零散的工具、模型、会话像设备一样装进一个机架里统一管理。这个直觉后来被验证得八九不离十openrig 要解决的核心问题就是当你同时用 Claude Code、Codex 这类命令行 AI 编程助手时会话散落在不同终端、不同目录、不同模型后端切来切去效率极低。它用 Node.js 做运行时用 tmux 做会话承载层把多个 AI 编程代理编排到同一个可切换的工作台里。如果你正在折腾 Claude Code 安装、Codex 安装、Node.js 安装这些事或者已经被cc switch local proxy failed while handling codex endpoint /responses这类报错折磨过那这篇内容就是写给你的。我会从整体设计思路讲到具体落地步骤把 Node.js 环境、tmux 会话管理、Claude Code 与 Codex 的接入、本地模型对接比如 LM Studio、DeepSeek、GLM、Qwen这些环节全部串起来。不管你是刚接触命令行 AI 工具的新手还是已经踩过一堆坑的老手都能从里面找到能直接抄作业的部分。需要先说明一点openrig 本身是一个偏编排层的工具它不替代 Claude Code 或 Codex而是站在它们之上做会话与进程管理。理解这个定位很关键否则你会误以为装完 openrig 就万事大吉结果发现模型还是得自己配。下面我按设计思路 → 核心细节 → 实操落地 → 问题排查的顺序展开中间穿插我自己踩过的坑。2. 整体设计与思路拆解为什么要用 tmux 做底座2.1 命令行 AI 助手的真实痛点Claude Code 和 Codex 这类工具本质上是常驻在终端里的对话式代理。它们有几个共同特征启动慢要加载上下文、建立连接、状态有粘性会话历史、当前工作目录、已加载的文件、需要长时间挂着跑长任务时不能关终端。这就带来一个很现实的问题——你不可能每换一个项目就重开一个终端窗口然后重新走一遍登录、配置、加载的流程。我早期的做法是开一堆终端标签页每个标签页跑一个 Claude Code 或 Codex 实例。用了两周就崩溃了标签页越开越多找不清哪个是哪个SSH 断线后进程全挂想在手机或另一台机器上接着看进度根本做不到。这些痛点的本质是——缺少一个稳定的、可持久化、可远程接入的会话层。2.2 tmux 为什么是天然答案tmux 恰好补上了这一层。它是一个终端复用器核心能力有三个会话持久化断开连接后进程继续跑、窗口与面板分割一个会话里塞多个终端、可编程控制通过命令行指令操作会话。把 AI 代理跑在 tmux 会话里等于给每个代理分配了一个永不掉线的房间你随时可以推门进去看它在干什么。openrig 选择 tmux 而不是自己造一套进程管理我认为是很务实的决策。自研会话管理要处理 PTY 分配、信号转发、终端尺寸同步、断线重连工作量巨大且容易出 bugtmux 这些能力已经打磨了十几年稳定性和跨平台性都经过验证。用 Node.js 去驱动 tmux相当于用一门擅长处理 IO 和子进程的语言去指挥一个成熟的终端基础设施分工非常清晰。2.3 Node.js 在其中的角色为什么是 Node.js 而不是 Python 或 Go从热词里高频出现的node.js安装、node.js官网下载、node.js lts下载能看出Claude Code 和 Codex 的官方分发方式本身就重度依赖 Node.js 生态——它们大多通过 npm 全局安装运行时也是 Node。openrig 用 Node.js 写最大的好处是同栈它可以直接复用你为了装 Claude Code 而已经配好的 Node 环境不需要你再额外装一套 Python 运行时。Node.js 的child_process模块能很方便地 spawn 出 tmux 进程并与之通信node-pty这类库还能处理伪终端。加上 npm 生态里现成的参数解析、日志、配置管理库开发一个编排器的成本被压得很低。这就是选对底座事半功倍的典型。2.4 编排层要解决的三件事把 openrig 的职责拆开看它主要干三件事。第一是会话生命周期管理创建、列出、附加、销毁 tmux 会话每个会话对应一个 AI 代理实例。第二是配置注入把模型后端、API 地址、工作目录这些参数在启动代理时通过环境变量或配置文件传进去避免每次手敲。第三是多后端切换同一个工作台里Claude Code 走一个模型Codex 走另一个模型甚至同一个工具在不同会话里接不同的本地模型互不干扰。理解了这三件事你就明白 openrig 的价值不在功能多而在把重复劳动收敛掉。它让你从每次都要重新配一遍变成配一次之后一条命令进房间。3. 核心细节解析与实操要点环境、会话与模型接入3.1 Node.js 环境版本选择是第一道坎热词里有一条特别扎眼error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错我见过太多次根源是版本号写错了或者用了尚未发布的版本。Node.js 的版本策略是偶数大版本为 LTS长期支持奇数大版本为 Current尝鲜。生产环境一律选 LTS。截至我写这篇内容时稳妥的选择是 Node.js 20 LTS 或 22 LTS。安装方式上我强烈建议用版本管理器而不是直接下安装包。Linux/macOS 上用nvmWindows 上可以用nvm-windows或fnm。原因很简单Claude Code、Codex、openrig 对 Node 版本的要求可能不一致版本管理器让你能一条命令切换不用卸载重装。# 安装 nvm 后安装并切换到 LTS nvm install --lts nvm use --lts node -v # 确认版本应输出 v20.x 或 v22.x npm -v注意Windows 用户如果之前用官网安装包装过 Node装 nvm-windows 前要先卸载干净否则会出现两个 node 命令打架、where node指向旧路径的问题。这是新手最常踩的坑。3.2 tmux 的安装与基础配置tmux 在主流 Linux 发行版上一条命令就能装Ubuntu/Debian 用sudo apt install tmuxCentOS/RHEL 用sudo yum install tmuxmacOS 用brew install tmux。Windows 原生没有 tmux通常的做法是在 WSL2 里跑或者用 MSYS2/Cygwin 环境。如果你在 Windows 上折腾 Claude Code我建议直接上 WSL2体验和 Linux 一致省掉大量兼容性麻烦。装完之后建议先改一下默认前缀键。tmux 默认前缀是Ctrlb和不少编辑器的快捷键冲突我习惯改成Ctrla。在~/.tmux.conf里加一行# ~/.tmux.conf set -g prefix C-a unbind C-b bind C-a send-prefix set -g mouse on # 开启鼠标支持方便滚动和选面板 set -g history-limit 50000 # 加大回滚缓冲AI 输出长的时候很有用history-limit这个参数特别值得调大。AI 代理的输出动辄几百上千行默认 2000 行的缓冲很快就被冲掉了想往回翻看它刚才说了什么结果发现已经被顶没了。调到 50000 之后基本够用。3.3 Claude Code 与 Codex 的安装差异这两个工具虽然都是命令行 AI 编程助手但安装和配置路径不太一样得分开说。Claude Code 通常通过 npm 全局安装装完后用claude命令启动。它的配置一般放在用户目录下的隐藏文件夹里登录走的是账号授权流程。热词里出现的your organization has disabled claude subscription access for claude code和note: claude code might not be available in your country前者是组织管理员在后台关掉了访问权限后者是区域可用性问题这两个都不是你本地环境能解决的遇到只能换账号或换方案。Codex 的安装方式类似但它的配置更偏向模型端点 API Key的模式所以你会看到codex接入deepseek、codex配置、codex登录这类搜索。Codex 对配置文件的格式比较敏感热词里codex is ignoring 1 unrecognized configuration setting. check for typos or d就是典型的配置项拼写错误——它读到一个不认识的键直接忽略并警告。这种时候别慌按提示检查拼写即可。# 全局安装示例具体包名以官方为准 npm install -g anthropic-ai/claude-code npm install -g openai/codex # 验证 claude --version codex --version提示全局安装如果报权限错误EACCES不要用sudo npm install -g那会把文件属主搞乱。正确做法是配置 npm 的全局目录到用户空间或者用 nvm 管理 Nodenvm 装的 Node 全局包天然在用户目录下不会有权限问题。3.4 本地模型接入LM Studio、DeepSeek、GLM、Qwen热词里claude code 调用lmstudio的本地模型、codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型这几条指向同一个需求把 AI 编程助手接到非官方的模型后端上。这背后的动机很实际——官方模型可能贵、可能区域受限、可能你想用本地跑的模型保证数据不出机器。接入的核心原理是兼容 OpenAI 接口协议。绝大多数本地推理工具LM Studio、Ollama 等和国产模型服务DeepSeek、GLM、Qwen都提供 OpenAI 兼容的/v1/chat/completions端点。你只要把 AI 助手的 base URL 指向这个端点再填上对应的 API Key本地模型通常随便填一个非空值就能跑通。以 LM Studio 为例在它的界面里启动本地服务器默认监听http://localhost:1234。然后在 Claude Code 或 Codex 的配置里把 base URL 设成http://localhost:1234/v1模型名填你在 LM Studio 里加载的那个模型标识。这里有个细节模型名必须和 LM Studio 里显示的完全一致大小写、连字符都不能错否则会报模型不存在。3.5 关于 cc switch 与代理转发热词里那条cc switch local proxy failed while handling codex endpoint /responses值得单独拎出来讲。这类工具cc switch 之类的作用是在本地起一个代理把 AI 助手的请求转发到不同后端实现一个入口多后端切换。报错信息说的是在处理 Codex 的/responses端点时本地代理失败了。这个报错的常见原因有三个。一是代理进程没起来或者端口被占请求发过去没人接。二是端点路径不匹配——Codex 用的是/responses而不是标准的/chat/completions如果你的代理只实现了后者转发就会 404。三是后端模型不支持 Codex 期望的请求格式比如某些模型不支持流式或特定的参数结构。排查顺序建议是先确认代理进程活着curl一下本地端口再看代理日志里请求打到了哪个路径最后确认后端模型是否兼容。4. 实操过程与核心环节实现把 openrig 跑起来4.1 前置检查清单动手之前先把这几项确认一遍能省掉后面一大半的排查时间。检查项命令期望结果Node.js 版本node -vv20.x 或 v22.xLTSnpm 可用npm -v正常输出版本号tmux 已装tmux -V输出 tmux 版本Claude Codeclaude --version输出版本号Codexcodex --version输出版本号本地模型服务curl http://localhost:1234/v1/models返回模型列表 JSON这张表看着简单但每一条我都见过有人栽在上面。尤其是最后一条很多人以为 LM Studio 开着界面就是服务起来了其实要在里面手动点Start Server才会监听端口。4.2 安装 openrig 与初始化openrig 作为 Node.js 工具安装方式大概率是 npm 全局安装或从源码构建。假设它已经发布到 npm流程如下# 方式一npm 全局安装 npm install -g openrig # 方式二从源码构建如果还没发布 git clone openrig-repo cd openrig npm install npm run build npm link # 把本地构建的包链接到全局方便调试npm link这一步在开发阶段很实用它让你改完源码后不用重新安装就能生效。装完后跑一下openrig --help看看它暴露了哪些子命令。通常会有create、list、attach、kill这类会话管理命令以及config之类的配置命令。4.3 创建第一个编排会话假设 openrig 的用法是openrig create name --tool claude|codex --model model那么创建一个接本地 LM Studio 模型的 Claude Code 会话大概是这样openrig create work-claude \ --tool claude \ --model local-qwen \ --base-url http://localhost:1234/v1 \ --api-key dummy-key \ --dir ~/projects/my-app这条命令背后 openrig 做的事是新建一个名为work-claude的 tmux 会话在会话里设置好环境变量base URL、API Key、模型名切换到指定工作目录然后启动claude进程。之后你用openrig attach work-claude就能进到这个会话里看到 Claude Code 已经在跑了。再创建一个接 DeepSeek 的 Codex 会话openrig create work-codex \ --tool codex \ --model deepseek-chat \ --base-url https://api.deepseek.com/v1 \ --api-key sk-xxxxxxxx \ --dir ~/projects/my-app两个会话独立运行互不干扰。你可以在work-claude里让 Claude Code 读代码在work-codex里让 Codex 写测试两边用不同的模型各取所长。4.4 会话切换与日常操作日常使用中最高频的操作就是进房间和出房间。tmux 的分离快捷键是Ctrlb然后按d如果你改过前缀就是Ctrla再按d。分离之后进程继续在后台跑你随时可以再 attach 回去。# 列出所有 openrig 管理的会话 openrig list # 进入某个会话 openrig attach work-claude # 在会话内分离不终止进程 # 按 Ctrla 然后 d # 终止某个会话 openrig kill work-codex我个人的习惯是给每个项目配一对会话一个 Claude Code 负责读和想理解代码、给方案一个 Codex 负责写和改生成代码、跑测试。两个会话共享同一个工作目录但用不同的模型相当于让两个不同风格的助手协作。4.5 参数选择背后的计算逻辑配置里几个关键参数怎么选值得说清楚。上下文窗口决定了 AI 一次能看到多少代码本地模型受显存限制窗口通常比云端小。如果你要它理解一个几千行的项目窗口太小会频繁截断效果大打折扣。选模型时先看它的上下文长度再对比你的项目规模。并发数方面本地模型服务通常一次只能处理一个请求除非显式配置了并行所以别指望同时开五个会话都接同一个本地模型还能流畅。真要并行要么给本地服务配多实例要么把部分会话切到云端模型。超时时间容易被忽略。本地模型首次加载模型权重可能要几十秒如果客户端超时设得太短比如默认 30 秒第一次请求就会失败。建议把超时调到 120 秒以上给冷启动留足余量。5. 常见问题与排查技巧实录5.1 高频报错速查表把热词里出现的报错和我在实践中遇到的整理成一张表方便对照排查。报错关键词可能原因排查方向node.js v24.21.0 is not yet released版本号不存在或写错改用 LTS 版本如 20/22cc switch local proxy failed ... /responses代理未启动或端点不匹配检查代理进程、确认/responses路径codex is ignoring 1 unrecognized configuration setting配置项拼写错误逐字核对配置键名your organization has disabled claude subscription access组织权限被关闭换账号或联系管理员codex无法加载组织设置配置拉取失败或网络问题检查配置源、重试登录claude code might not be available in your country区域可用性限制属于服务侧限制本地无法解决5.2 会话相关的坑坑一tmux 会话里的环境变量不生效。有时候你在 shell 里export了 API Key但 openrig 创建的会话里读不到。原因是 tmux 启动新会话时可能不继承当前 shell 的全部环境。解决办法是把关键变量写进 openrig 的配置文件或者用tmux set-environment显式注入。坑二SSH 断线后会话丢失。如果你直接在 SSH 会话里跑openrig create而没有用 tmux 的持久化断线后进程可能被 SIGHUP 杀掉。正确姿势是确保 openrig 内部确实用了 tmux 的 detached 模式创建会话这样断线不影响。坑三中文输出乱码。在 tmux 里跑 AI 代理如果 locale 没配好中文会显示成方块或乱码。检查locale命令输出确保LANG和LC_ALL是en_US.UTF-8或zh_CN.UTF-8。在~/.tmux.conf里加set -g default-terminal screen-256color也有帮助。5.3 模型接入的坑坑一本地模型响应慢导致超时。前面提过冷启动慢。除了调大超时还可以在正式用之前先发一个预热请求让模型加载进显存后续请求就快了。坑二模型名不匹配。本地服务里模型标识和你配置里写的对不上是最常见的模型不存在来源。用curl http://localhost:1234/v1/models拿到准确的名字复制粘贴别手敲。坑三流式输出中断。有些代理或中间层对 SSE服务器推送事件支持不完整导致流式输出到一半断掉。如果遇到先试试关掉流式如果工具支持确认是流式的问题还是模型本身的问题。5.4 我自己的避坑心得折腾这套东西大半年有几条经验是文档里不会写的。第一永远先跑通最小闭环再叠加复杂度。先用官方模型把 Claude Code 跑通确认会话管理没问题再去接本地模型。一上来就本地模型 代理 多会话出问题你根本不知道是哪一层坏了。第二日志是你的朋友。openrig、tmux、AI 代理、本地模型服务每一层都有自己的日志。出问题时按从外到内的顺序看先看 openrig 有没有成功创建会话再看 tmux 里进程活没活再看代理日志最后看模型服务日志。逐层排除比瞎猜快得多。第三配置文件用版本管理。你的 openrig 配置、tmux 配置、模型端点配置都值得放进一个 git 仓库。换机器时一键恢复出问题时能对比上次能用和这次不能用的差异。我吃过亏——某次改了个配置项忘了改回来排查了两小时才发现是自己手贱。第四给会话起有意义的名字。session1、session2这种名字过两天你自己都忘了哪个是哪个。用项目名-工具名-用途的格式比如myapp-claude-review、myapp-codex-test一眼就知道该进哪个房间。6. 关于扩展方向的一点个人想法openrig 这类编排器的想象空间其实挺大。往小了说它可以加个会话模板功能把常用的配置组合存成模板一条命令拉起一整套工作环境。往大了说它可以做成一个多代理协作框架——让 Claude Code 和 Codex 互相 review 对方的输出一个写一个审形成闭环。我试过手动做这件事在 Claude Code 里让它生成方案复制到 Codex 会话里让它挑毛病再把意见拿回来。流程能跑通但全靠手工搬运效率不高。如果 openrig 能把这种代理间消息传递做进去价值会大很多。另一个方向是和编辑器集成。热词里vscode配置claude code、claude code for vs code、vscode接入claude code出现频率很高说明很多人希望在 VS Code 里直接用。openrig 如果能提供一个 VS Code 插件把 tmux 会话的状态同步到编辑器侧边栏点一下就能切换会话、查看输出那体验会顺滑不少。不过这属于锦上添花核心的会话编排能力才是根基。最后分享一个我日常用的小技巧给 tmux 会话配一个状态栏显示当前会话名和正在跑的模型。这样你 attach 进去的第一眼就知道自己在哪个房间、用的是哪个模型避免以为在用本地模型结果请求打到了云端这种乌龙。在~/.tmux.conf里加一行set -g status-right #{session_name}就能实现简单但实用。