1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟“rig”在英文里常指设备支架或矿机机架。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编程助手大概率已经在某个 issue 或讨论帖里见过它。openrig 本质上是一个面向 AI 编程 CLI 工具的本地运行编排层它把 Node.js 运行时、tmux 会话管理、多模型接入配置这几件琐碎但容易出错的事情收敛成一套可复现的启动流程。我最初接触它是因为一个很具体的痛点在 Ubuntu 服务器上同时跑 Claude Code 和 Codex每次重连 SSH 之后会话就断了重新配置环境变量、切换 API 端点、确认 Node 版本一套流程走下来十几分钟就没了。更麻烦的是Claude Code 和 Codex 对 Node.js 版本的要求并不完全一致全局装一个版本经常顾此失彼。openrig 出现的意义就在于它不试图替代这些工具而是给它们提供一个稳定的“底座”。它适合谁三类人最值得关注。第一类是经常在远程服务器上使用 AI 编程助手的开发者tmux 会话保持是刚需第二类是需要在本机同时管理多个模型端点的人比如白天用云端模型、晚上切到 LM Studio 本地模型第三类是刚入门 Claude Code 或 Codex 的新手面对 Node.js 安装、环境变量配置、组织权限报错这些坑openrig 能帮你跳过大量试错。需要说明的是openrig 目前并不是一个官方发布的大型框架更多是社区实践中沉淀出来的一套编排思路和配套脚本。所以下面讲的内容一部分来自项目本身的定位一部分是我在实际搭建过程中基于常见实践补全的细节你在复现时可以根据自己的环境做调整。2. 核心设计思路为什么是 Node.js tmux 这套组合2.1 Node.js 版本管理是整个链条的地基Claude Code 和 Codex 的 CLI 都是 Node.js 生态的产物这一点决定了你的运行环境必须有一个可用的 Node.js。热搜词里频繁出现“node.js安装”“node.js官网下载”“node.js lts下载”“error installing 24.21.0: node.js v24.21.0 is not yet released”说明大量用户在版本选择上栽过跟头。我的建议很明确不要追最新版锁定 LTS。Node.js 的奇数版本是实验性的偶数版本才是长期支持。比如 v20 和 v22 都是 LTS而 v24 在某个时间点可能还没正式发布你如果照着某个教程敲了nvm install 24.21.0就会直接撞上“is not yet released”的报错。openrig 的思路是把 Node 版本写进配置用 nvm 或 fnm 做版本切换而不是依赖系统全局的那一个。为什么不用系统自带的 Node因为 Ubuntu 的 apt 源里的 Node 版本往往偏旧而 Claude Code 这类工具更新频繁旧版本可能在某个版本之后就不再兼容。用版本管理器还有一个好处你可以给 Claude Code 和 Codex 分别指定不同的 Node 版本互不干扰。2.2 tmux 解决的是“会话存活”这个隐形需求很多人第一次用 Claude Code 是在本地终端里关掉窗口任务就没了。但一旦你把它放到远程服务器上SSH 断线就意味着进程被杀。tmux 在这里扮演的角色是会话容器你在 tmux 里启动 Claude Code即使 SSH 断开进程依然在服务器上跑着下次连上去tmux attach就能接着看。openrig 把 tmux 纳入核心设计还有一个更细的考量Claude Code 支持直接执行终端命令Codex 也有类似的交互能力。如果你让它们在裸终端里跑一个误操作可能影响整个 shell 环境。放进 tmux 的独立窗口或面板里相当于给每个 AI 助手划了一块“自留地”出问题只影响那个 pane不会波及你的主工作环境。2.3 多端点切换是绕不开的现实需求热搜词里“cc switch local proxy failed while handling codex endpoint /responses”“使用cc switch 接入 deepseek v4, qwen, glm等模型”“codex接入deepseek”这些反映的是一个普遍场景用户不想只绑死在一个模型上。Claude Code 默认走 Anthropic 的端点Codex 默认走 OpenAI 的端点但实际使用中你可能因为成本、速度、可用性等原因需要切换到 DeepSeek、Qwen、GLM 或者本地的 LM Studio。openrig 在这方面的价值是把端点配置从工具内部抽离出来。它不修改 Claude Code 或 Codex 的源码而是通过环境变量和配置文件在启动时注入不同的 base URL 和 API Key。这样做的好处是切换成本极低你不需要每次手动改配置文件只需要在 openrig 的配置里选一个 profile。3. 环境搭建实操从裸机到可运行状态3.1 Node.js 安装的三种路径与选择依据在 Ubuntu 上装 Node.js常见的有三条路apt、nvm、官方二进制包。我逐一说说适用场景。apt 最简单sudo apt install nodejs npm两条命令搞定但版本通常落后。如果你只是临时跑一下不介意版本旧可以用。但 Claude Code 和 Codex 的某些版本会检查 Node 版本号太旧会直接拒绝启动。nvm 是我最推荐的方式。安装命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后需要重新加载 shell 配置然后nvm install 22装 LTS 版本nvm use 22切换。nvm 的好处是版本隔离彻底每个项目可以用不同的 Node 版本。openrig 的配置里通常会写一个.nvmrc文件里面就一行版本号进入目录时nvm use自动切换。官方二进制包适合不想装额外管理工具的人。去 Node.js 官网下载 LTS 的 Linux 二进制压缩包解压到/usr/local或~/.local然后把 bin 目录加进 PATH。这种方式可控性强但升级时要手动替换。注意如果你在安装时看到“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”不要慌这不是你的问题是这个版本号本身不存在或还没发布。换成nvm install --lts即可。3.2 tmux 的基础配置与会话规划tmux 安装很简单sudo apt install tmux即可。但默认配置用起来不太顺手我建议至少改几个地方。在~/.tmux.conf里加上set -g mouse on set -g base-index 1 setw -g pane-base-index 1 set -g history-limit 10000mouse on让你可以用鼠标切换面板和滚动base-index 1让窗口编号从 1 开始而不是 0符合直觉。history-limit调大是因为 Claude Code 的输出可能很长默认的 2000 行不够翻。会话规划上我的习惯是给 openrig 单独开一个 session名字叫rig。里面分三个窗口窗口 1 跑 Claude Code窗口 2 跑 Codex窗口 3 留作 shell 用来查日志和改配置。这样tmux attach -t rig一进去就是完整的工作台。3.3 Claude Code 与 Codex 的安装要点Claude Code 的安装方式取决于你用的版本。如果是 npm 包形式npm install -g anthropic-ai/claude-code是常见做法。安装后第一次运行会引导你登录或配置 API Key。热搜词里“your organization has disabled claude subscription access for claude code”这个报错通常是因为你的账号所属组织关闭了订阅访问权限需要在组织设置里开启或者换用 API Key 方式而非订阅登录。Codex 的安装类似npm install -g openai/codex或者从官网下载安装包。Windows 用户注意热搜词里“codex安装 windows桌面版”说明有桌面版可选但如果你要用 openrig 这套编排建议还是用 CLI 版本因为 tmux 是 Linux/macOS 生态的东西Windows 上需要 WSL 才能配合。安装完成后先别急着配置 openrig单独跑一下claude --version和codex --version确认两个工具都能正常启动。这一步是排错的基础如果单独都跑不起来套上 openrig 只会更难排查。4. openrig 配置文件的写法与参数详解4.1 配置文件结构设计openrig 的配置我习惯用一个 YAML 文件来管理放在~/.config/openrig/config.yaml。结构大致分三块runtime、sessions、profiles。runtime 块定义 Node 版本和 tmux 的基础参数。sessions 块定义要启动哪些 AI 工具、各自在哪个 tmux 窗口、启动命令是什么。profiles 块定义不同的模型端点组合每个 profile 包含 base URL、API Key 环境变量名、以及可选的额外参数。这样设计的原因是关注点分离。你想换模型时只改 profiles想调整窗口布局时只改 sessions想升级 Node 时只改 runtime。不会出现改一个地方牵连一片的情况。4.2 端点配置的关键参数与常见坑以接入 DeepSeek 为例一个 profile 大概长这样profiles: deepseek: base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY model: deepseek-chat这里有几个细节值得展开。base_url的结尾要不要带/v1取决于工具的实现。Claude Code 和 Codex 对端点路径的拼接方式不同热搜词里“cc switch local proxy failed while handling codex endpoint /responses”这个报错很可能就是路径拼接出了问题——Codex 期望的是/responses结尾但代理层给的是别的路径。我的经验是先用 curl 手动测端点。比如curl -H Authorization: Bearer $KEY https://api.deepseek.com/v1/models确认能返回模型列表再往 openrig 里填。这样能把网络问题和配置问题分开。api_key_env用环境变量名而不是直接写 Key是为了避免配置文件泄露。Key 放在~/.bashrc或单独的.env文件里配置文件可以安全地提交到私有仓库。4.3 本地模型接入的特殊处理热搜词里“claude code 调用lmstudio的本地模型”是一个高频需求。LM Studio 默认在http://localhost:1234/v1提供 OpenAI 兼容接口。接入时要注意两点一是 LM Studio 的模型名要和你加载的模型一致二是本地模型的上下文窗口可能比云端小Claude Code 如果发送超长上下文会报错。在 openrig 里本地模型的 profile 我会额外加一个max_tokens限制避免请求过大。另外本地模型不需要真实的 API Key但很多工具会检查这个字段是否存在所以随便填一个非空字符串即可。5. 启动流程与日常使用习惯5.1 一键启动脚本的编写openrig 的核心体验是“一条命令进入工作状态”。我写了一个rig-up.sh逻辑是检查 tmux 会话是否存在不存在就创建在会话里按配置启动各个工具最后 attach 进去。脚本的关键片段#!/bin/bash SESSIONrig if ! tmux has-session -t $SESSION 2/dev/null; then 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 fi tmux attach -t $SESSIONsend-keys后面的C-m相当于按回车。这个脚本跑一次三个窗口就都起来了。5.2 日常切换与状态查看日常使用中最频繁的操作是切换 profile。我的做法是在 shell 窗口里放一个rig-switch函数接受 profile 名作为参数更新环境变量后重启对应的 tmux 窗口。这样不需要退出整个会话。状态查看方面tmux 的状态栏可以配置显示当前 profile 名。在~/.tmux.conf里加一行set -g status-right #{RIG_PROFILE}然后在切换 profile 时用tmux set-environment更新这个变量。这样你一眼就能看到当前用的是哪个端点避免在错误的模型上发请求。6. 常见报错与排查手册6.1 安装阶段的典型问题报错信息可能原因解决方向node.js v24.21.0 is not yet released版本号不存在或未发布改用nvm install --ltserror installing 24.21.0同上或网络问题检查网络换 LTS 版本codex is ignoring 1 unrecognized configuration setting配置文件里有拼写错误或未知字段逐行核对配置项名称your organization has disabled claude subscription access组织权限限制改用 API Key 登录或联系管理员6.2 运行阶段的端点问题“cc switch local proxy failed while handling codex endpoint /responses”这个报错我在测试时遇到过。排查下来是代理层把 Codex 的请求转发到了错误的路径。Codex 的/responses端点和 OpenAI 标准的/chat/completions不一样如果你的代理只处理了后者前者就会 404。解决方法是确认代理层是否支持 Codex 的端点格式。如果不支持要么换一个支持的工具要么直接用 Codex 官方端点不走代理。另一个常见问题是“codex无法加载组织设置”。这通常出现在企业账号场景Codex 启动时会尝试拉取组织级配置如果网络不通或权限不足就会卡住。临时方案是在配置里关闭组织设置加载用个人配置覆盖。6.3 会话与进程管理问题tmux 会话里的进程有时候会僵死表现为输入没反应但窗口还在。这时候不要直接 kill 整个会话先试试Ctrl-C中断当前命令如果不行在 shell 窗口里ps aux | grep claude找到进程号单独 kill 掉然后在原窗口重新启动。还有一种情况是 Node 进程占满内存导致 OOM。Claude Code 处理大文件时可能吃很多内存如果服务器内存小建议在启动命令前加NODE_OPTIONS--max-old-space-size2048限制堆大小避免拖垮整台机器。7. 我踩过的坑与实用建议第一个坑是不要混用全局安装和 nvm。我有一次先用 apt 装了 Node后来又用 nvm 装了一个版本结果which node指向的路径和npm的路径不一致装出来的 Claude Code 跑不起来。后来统一用 nvm把 apt 的 Node 彻底卸载才干净。第二个坑是API Key 的引号问题。在.env文件里写DEEPSEEK_API_KEYsk-xxx有些加载器会把引号也当成值的一部分导致认证失败。建议不加引号直接DEEPSEEK_API_KEYsk-xxx。第三个坑是tmux 里的环境变量不会自动继承。你在.bashrc里 export 的变量在已经运行的 tmux 会话里是看不到的。切换 profile 后需要手动tmux set-environment或者重启会话。这个我折腾了很久才搞明白。第四个坑是本地模型的并发限制。LM Studio 默认可能只允许一个并发请求Claude Code 如果同时发多个请求会排队甚至超时。在 LM Studio 的设置里把并发数调大或者在使用时避免同时触发多个任务。最后分享一个提高效率的小习惯把常用的排查命令做成 alias比如alias riglogtmux capture-pane -t rig:claude -p这样不用 attach 进去就能看到 Claude Code 窗口的最后输出快速判断它是不是卡住了。这个技巧在远程服务器上特别省事。