1. 从 openrig 说起一个把 Claude Code 和 Codex 装进 tmux 的编排器第一次看到openrig这个名字我下意识把它拆成了 open rig——rig 在工程语境里就是装配台、机架的意思把一堆零散的工具、模型、会话像搭机架一样组装起来。这个直觉后来被验证是对的openrig 本质上是一个面向 AI 编码代理coding agent的本地编排层它要解决的核心问题不是怎么调用模型而是怎么让 Claude Code、Codex 这类命令行代理在 tmux 会话里稳定地跑起来、切得动、看得见、断得掉。如果你最近在折腾 Claude Code 或者 Codex CLI大概率踩过这些坑Node.js 版本对不上导致error installing 24.21.0: node.js v24.21.0 is not yet released or is not availableCodex 登录后提示your organization has disabled claude subscription access for claude code切第三方 API 时冒出cc switch local proxy failed while handling codex endpoint /responses或者 Codex 启动时甩一句codex is ignoring 1 unrecognized configuration setting. check for typos or d...。这些报错单看都很碎但背后其实是同一类问题——代理进程的生命周期、环境变量、端点路由没有被统一管理。openrig 想做的就是把这层管理收拢到一个可复现的机架里。这篇文章适合三类人看一是刚接触 Claude Code / Codex、还在纠结 Node.js 装哪个版本的新手二是已经在用但被多会话、多模型切换折磨的中级用户三是想自己搭一套本地代理编排、接 LM Studio 或 DeepSeek 这类本地/第三方模型的折腾党。我会从设计思路讲到实操细节把 tmux、Node.js、端点代理这几块拆开揉碎尽量让你看完能直接抄作业。2. 整体设计思路为什么是 tmux Node.js 代理层2.1 为什么编排层要选 tmux 而不是普通终端很多人第一反应是我开几个终端窗口不就行了我一开始也这么干直到同时跑三个 Claude Code 会话加两个 Codex 会话窗口切到怀疑人生。tmux 的价值在这里不是好看而是会话持久化 可编程控制。普通终端窗口关掉里面的代理进程就没了tmux 的 session 是独立于终端存在的你 SSH 断了、笔记本合盖了回来tmux attach一切照旧。对于跑长任务的编码代理来说这一点是刚需——Claude Code 处理一个大重构可能跑十几分钟你不可能一直盯着。更关键的是 tmux 可以被脚本控制。openrig 这类工具能一键起一组会话、给每个会话发指令、抓取输出靠的就是tmux send-keys、tmux capture-pane这些命令。你可以把它理解成一个进程的窗口管理器代理跑在里面编排器在外面遥控。提示tmux 的 session、window、pane 三层结构要分清。一个 session 可以开多个 window一个 window 可以切多个 pane。openrig 通常一个代理实例占一个 window 或 pane方便单独 attach 查看。2.2 Node.js 版本所有报错的万恶之源热词里node.js安装、node.js lts下载、error installing 24.21.0出现频率极高这不是偶然。Claude Code 和 Codex CLI 都是 Node.js 生态的工具它们对 Node 版本有硬性要求而 Node 的版本发布节奏又特别快——奇数版本是当前版偶数版本才是 LTS长期支持。那个node.js v24.21.0 is not yet released or is not available的报错本质是你用的版本管理器nvm、fnm、volta 之类去拉一个还不存在的版本号。Node 24 这条线当时可能只发到 24.x 的某个小版本你写了个 24.21.0它自然找不到。解决办法不是硬凑版本号而是先查清楚当前 LTS 到底是哪个大版本再装对应的最新小版本。我的经验是永远优先装 LTS不要追 Current。LTS 的兼容性经过验证代理工具的作者测试的也是 LTS。你追 Current 图新鲜结果就是各种原生模块编译失败、依赖不匹配。2.3 代理层为什么要有个中间人cc switch local proxy failed while handling codex endpoint /responses这个报错暴露了一个核心矛盾Claude Code 和 Codex 各自期望的 API 端点格式不一样而你想让它们都接到同一个后端比如 DeepSeek、GLM、Qwen或者本地的 LM Studio。Claude Code 走的是 Anthropic 风格的/v1/messagesCodex 走的是 OpenAI 风格的/responses或/v1/chat/completions。你要用第三方模型就得有个代理层做协议转换 端点路由。openrig 里的 switch 和 proxy 就是干这个的。代理层失败的常见原因有三类一是端点路径写错/responses和/v1/responses差一个前缀就 404二是请求体格式没转换Anthropic 的system字段和 OpenAI 的messages[0].rolesystem不是一回事三是流式响应SSE没处理好导致代理挂起。排查时优先看代理的日志别一上来就怀疑模型。3. 核心细节解析环境、配置、端点三件套3.1 Node.js 环境搭建的实操要点先说安装。Windows 用户直接去 Node.js 官网下 LTS 的.msi安装包最省事但如果你要同时维护多个项目、多个 Node 版本强烈建议用版本管理器。macOS/Linux 用nvm或fnmWindows 可以用nvm-windows或fnm。# 以 fnm 为例跨平台速度快 # 安装 fnm 后装当前 LTS fnm install --lts fnm use --lts node -v # 确认版本应该是 v20.x 或 v22.x 这类偶数版本 npm -v装完 Node 之后Claude Code 和 Codex 的安装通常是全局 npm 包npm install -g anthropic-ai/claude-code npm install -g openai/codex这里有个坑全局包和 Node 版本是绑定的。你用 fnm 切了 Node 版本之前装的全局包可能就消失了因为不同 Node 版本有各自的全局目录。所以要么固定一个 LTS 版本别乱切要么每次切完重装。我个人的做法是给代理工具单独锁定一个 LTS用.node-version文件固定下来。注意如果安装时报error installing 24.21.0先别急着改版本号运行fnm ls-remote或nvm ls-remote看看远端到底有哪些版本挑一个真实存在的 LTS 小版本。3.2 Claude Code 与 Codex 的配置差异这两个工具虽然都是命令行代理但配置哲学不太一样。Claude Code 更开箱即用配置文件通常在用户目录下的.claude或项目里的.claude/settings.jsonCodex 的配置更偏 TOML 风格常见的是~/.codex/config.toml。Codex 那个codex is ignoring 1 unrecognized configuration setting. check for typos的警告几乎百分百是配置文件里写了它不认识的键。Codex 的配置项更新比较快你从某篇教程抄来的键名可能已经废弃了。遇到这个警告先去看官方文档当前的配置 schema别硬扛。Claude Code 这边your organization has disabled claude subscription access for claude code是账号层面的限制不是配置问题。这种情况要么换账号要么走 API Key 模式而不是订阅模式。热词里claude code 调用 lmstudio 的本地模型就是典型的绕开官方订阅、接本地模型的需求这时候代理层就派上用场了。配置项Claude CodeCodex配置格式JSONTOML常见路径~/.claude/~/.codex/config.toml端点风格Anthropic/v1/messagesOpenAI/responses模型指定环境变量或配置配置或命令行参数常见报错订阅权限、国家限制配置键拼写、端点 4043.3 端点路由/responses到底该怎么配cc switch local proxy failed while handling codex endpoint /responses这个报错我拆过好几次。核心是 Codex 请求的路径和你代理实际监听的路径对不上。假设你的代理跑在http://127.0.0.1:8080Codex 配置里写的 base URL 是http://127.0.0.1:8080/v1那它实际请求的是http://127.0.0.1:8080/v1/responses。如果你的代理只处理/responses没有/v1前缀就会 404然后报这个错。排查顺序建议这样先curl一下代理的健康检查端点确认代理活着。用curl -X POST手动打一下/v1/responses看返回什么。对比 Codex 配置里的 base URL 和代理实际路由。看代理日志里收到的原始路径是什么。# 手动验证代理端点 curl -i http://127.0.0.1:8080/v1/responses \ -H Content-Type: application/json \ -d {model:your-model,input:hello}如果返回 404就是路径问题如果返回 400 或 422是请求体格式问题如果一直挂着不返回是流式处理问题。这三种情况的修法完全不同别混为一谈。4. 实操过程从零搭一套可复现的代理编排4.1 第一步把 Node.js 和工具链钉死我习惯先建一个项目目录把所有版本信息写进文件保证换机器能复现。mkdir openrig-lab cd openrig-lab echo lts/* .node-version # fnm 会读这个文件 fnm use node -v然后装工具。注意全局安装和本地安装的区别如果你想让项目自包含可以本地装然后用npx调用。npm init -y npm install anthropic-ai/claude-code openai/codex # 或者全局 npm install -g anthropic-ai/claude-code openai/codex装完先别急着配模型先跑claude --version和codex --version确认二进制能起来。这一步能过滤掉一半的装完用不了问题。4.2 第二步用 tmux 起一个持久会话tmux new-session -d -s openrig tmux new-window -t openrig -n claude tmux new-window -t openrig -n codex tmux list-windows -t openrig这样你就有了一个叫openrig的 session里面两个 window 分别给 Claude Code 和 Codex。之后tmux attach -t openrig就能进去Ctrl-b加数字切 window。为什么要分 window 而不是分 pane因为代理的输出经常很长pane 切小了看不清。window 是全屏的滚动查看更舒服。如果你要同时盯多个代理可以一个 window 里开多个 pane但每个 pane 至少留 80 列宽。提示tmux 默认的滚动缓冲区可能不够建议在~/.tmux.conf里加set -g history-limit 50000不然代理输出长了前面的内容会被截掉。4.3 第三步配置代理层接第三方或本地模型这是整个 openrig 最核心也最容易翻车的一环。假设你要把 Codex 接到本地 LM Studio它默认在http://127.0.0.1:1234/v1你需要一个代理把 Codex 的/responses请求转成 LM Studio 能懂的/v1/chat/completions。代理的职责可以概括成一张转换表来源目标需要做的转换Codex/responsesLM Studio/v1/chat/completions请求体字段映射、SSE 格式转换Claude Code/v1/messagesDeepSeek/v1/chat/completionssystem 字段位置、工具调用格式Claude Code/v1/messagesGLM/Qwen 兼容端点模型名映射、鉴权头替换写代理的时候最容易忽略的是流式响应。Claude Code 和 Codex 都默认用 SSE 流式接收如果你的代理把上游的流式响应缓冲成完整响应再返回客户端会一直等看起来就像卡死。正确做法是边收边转边发。// 代理流式转发的核心逻辑示意 app.post(/v1/responses, async (req, res) { res.setHeader(Content-Type, text/event-stream); res.setHeader(Cache-Control, no-cache); const upstream await fetch(http://127.0.0.1:1234/v1/chat/completions, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(convertRequest(req.body)), }); const reader upstream.body.getReader(); while (true) { const { done, value } await reader.read(); if (done) break; res.write(convertChunk(value)); // 逐块转换后写出 } res.end(); });这段代码的关键点是res.write而不是等全部收完再res.send。很多人第一次写代理就栽在这里。4.4 第四步把配置写进文件别靠记忆配置这东西靠记忆迟早出错。我建议把 Claude Code 和 Codex 的配置都落到文件里并且用环境变量管理密钥。# ~/.codex/config.toml 示例结构 # model your-model # model_provider local # [model_providers.local] # name local # base_url http://127.0.0.1:8080/v1 # env_key LOCAL_API_KEY# 环境变量写进 ~/.bashrc 或 ~/.zshrc export LOCAL_API_KEYyour-key export ANTHROPIC_BASE_URLhttp://127.0.0.1:8080Claude Code 接本地模型时ANTHROPIC_BASE_URL指向你的代理代理再把请求转给 LM Studio。这样 Claude Code 以为自己在跟 Anthropic 说话实际上请求全被代理接管了。注意密钥千万别硬编码进配置文件然后提交到 git。用环境变量或者用.env文件并加进.gitignore。5. 常见问题与排查技巧实录5.1 安装类问题速查报错根因解决node.js v24.21.0 is not yet released版本号不存在查ls-remote装真实存在的 LTS全局命令找不到Node 版本切换导致全局目录变了固定 LTS 或重装全局包npm install卡住网络或镜像源问题换镜像源检查代理设置原生模块编译失败缺构建工具链装 python、make、gcc 等5.2 登录与权限类问题your organization has disabled claude subscription access for claude code和claude code might not be available in your country这两类本质是账号和区域策略问题不是技术问题。能做的只有换用 API Key 模式、接第三方或本地模型、或者用支持的方式接入。别在这上面死磕浪费时间。Codex 的codex无法加载组织设置通常是登录态过期或配置文件损坏。先codex logout再codex login还不行就删掉~/.codex下的缓存重来。5.3 代理与端点类问题cc switch local proxy failed while handling codex endpoint /responses我前面拆过这里给个更细的排查清单代理进程是否在监听lsof -i :8080或netstat -ano | findstr 8080。路径前缀对不对/responsesvs/v1/responses。请求体字段名对不对Codex 用inputOpenAI 用messages。流式响应有没有被缓冲看代理是不是等全部收完才返回。上游模型服务活着吗直接 curl 上游端点。我踩过最深的一个坑是代理监听了localhost但 Codex 配置里写的是127.0.0.1在某些系统上这两个解析结果不一样导致连不上。统一用127.0.0.1最稳。5.4 实操心得几条血泪经验第一先跑通最小闭环再叠功能。别一上来就同时配 Claude Code、Codex、三个模型、两个代理。先让一个工具接一个模型跑通再加第二个。每加一个变量出问题的组合就翻倍。第二日志是你的命。代理层一定要打日志把收到的路径、请求体摘要、转发目标、响应状态都记下来。出问题时tail -f一看就明白。没有日志的代理等于黑盒。第三tmux 会话命名要有规律。我用openrig-claude、openrig-codex这种前缀tmux ls一眼能看出哪些是代理会话不会跟别的混。第四配置文件改动后要重启代理。很多人改了配置发现不生效就是因为代理进程还在用旧配置。养成改完就重启的习惯。第五别迷信教程里的版本号。热词里那些codex安装 csdn、claude code 入门教程的内容很多是几个月前的版本号早就过时了。以官方文档和--version实际输出为准。6. 把 openrig 用顺之后的几点延伸openrig 这套思路其实不局限于 Claude Code 和 Codex。任何命令行代理 多模型 需要持久会话的场景都能套比如你同时跑几个不同的本地模型做对比测试或者给团队搭一套共享的代理环境。tmux 负责会话Node.js 负责工具链代理层负责协议转换这三块解耦之后换任何一个组件都不影响其他部分。我现在的工作流是早上tmux attach -t openrig三个 window 分别是 Claude Code 接 DeepSeek、Codex 接本地 LM Studio、还有一个专门跑日志监控。哪个代理卡了切过去看一眼日志基本能定位。这套东西搭一次后面省下的时间远超搭建成本。如果你刚开始折腾我的建议是别追求一步到位。先把 Node.js 的 LTS 装对把 Claude Code 或 Codex 其中一个跑起来能正常对话了再去碰代理和第三方模型。顺序反了你会被一堆报错淹没最后分不清哪个是根因。踩坑不可怕可怕的是同时踩五个坑还找不到是哪个。
