1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的不是某个具体工具而是一种把散装零件拼成一台能跑的工作台的感觉。rig 在英文里本来就有装配、搭建、成套设备的意思open 则点明了它的开放属性。把这两个词放在一起再结合它周围出现的那一串关键词——Claude Code、Codex、Node.js、tmux——基本能勾勒出它想干的事给命令行 AI 编程助手搭一套开放、可复用、能长期运行的本地工作环境。为什么这件事值得单独拎出来讲因为现在用 Claude Code 或者 Codex 的人越来越多但绝大多数人卡在同一个地方装是装上了跑也能跑起来可一旦涉及多会话管理、本地模型接入、终端命令自动执行、跨平台配置立刻就乱成一锅粥。热词里那些报错信息就是最好的证据——cc switch local proxy failed while handling codex endpoint /responses、codex is ignoring 1 unrecognized configuration setting、your organization has disabled claude subscription access、the gpt-5.6-sol model is not supported when using codex这些不是个别现象而是整个生态还处在能用但不好用阶段的典型症状。openrig要处理的正是这些症状背后的结构性问题。它不是一个单点工具而更像一套约定俗成的装配方案用 Node.js 做运行时底座用 tmux 做会话容器把 Claude Code 和 Codex 这类 CLI 助手塞进同一个可管理的框架里再通过本地代理层去对接 LM Studio、DeepSeek、Qwen、GLM 这些模型端点。说白了它想让你从每次开个终端手动敲命令进化到有一套稳定的、可切换的、能后台常驻的工作台。这篇文章适合谁看如果你已经在用 Claude Code 或 Codex但被环境配置、模型切换、会话丢失这些问题反复折磨那这里的内容基本能对上你的痛点。如果你还没上手只是想搞清楚这套东西的运转逻辑那也可以把它当成一份装配说明书来读。我不会只给你一堆命令而是会把每一步背后的取舍讲清楚——为什么用 tmux 而不是 nohup为什么 Node.js 版本这么敏感为什么本地代理层是绕不开的一环。需要先说明的是openrig目前并没有一个官方定义的标准形态它更像社区里逐渐形成的一套实践共识。所以下面讲的内容一部分来自公开可查的工具文档一部分是我自己在搭类似环境时踩出来的经验。哪些是通用做法哪些是我的个人选择我会尽量标清楚方便你按自己的情况取舍。2. 底座选型Node.js 版本为什么成了第一道坎2.1 Node.js 在这套装配里的真实角色很多人以为 Node.js 只是个装依赖用的装完就不管了。但在 Claude Code、Codex 这类 CLI 工具的场景里Node.js 是运行时本身——这些工具大多是用 JavaScript/TypeScript 写的靠 npm 全局安装靠 Node 的解释器执行。这意味着 Node 的版本、npm 的路径、全局 bin 目录的位置任何一个出问题工具就直接起不来。热词里有一条特别典型error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错的意思是你指定的版本号在官方源里根本不存在。出现这种情况通常有两个原因一是你抄了别人的版本号但没核对二是某些版本管理工具比如 nvm的镜像源同步滞后导致它认为某个已发布版本不存在。这类问题的排查思路很简单——先去 Node.js 官网确认当前 LTS 的实际版本号再决定装哪个。2.2 LTS 还是 Current一个被低估的选择我的建议很明确生产环境一律用 LTS尝鲜才用 Current。原因不复杂。Claude Code 和 Codex 这类工具依赖的底层库比如各种 HTTP 客户端、终端渲染库在 LTS 上经过充分验证而 Current 版本经常引入破坏性变更导致某些依赖编译失败或者行为异常。具体到版本Node.js 20.x 是目前最稳的选择22.x 也可以但要注意部分老依赖可能还没跟上。热词里出现的node.js lts下载、node.js官网下载、node.js下载这些搜索说明很多人第一步就卡在去哪下、下哪个上。答案就是官网的 LTS 页面别去第三方站点那些地方经常夹带旧版本或者改过的安装包。在 Ubuntu 上装 Node.js 20我推荐用 NodeSource 的源而不是系统自带的 apt 版本。系统自带的往往太旧装完 Claude Code 可能直接报语法错误。命令大致是这样curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完用node -v和npm -v各确认一次。这里有个细节如果你之前用 apt 装过旧版 Node最好先sudo apt remove nodejs清干净否则可能出现两个版本打架which node指向的和你以为的不是同一个。2.3 全局安装路径的坑npm 全局安装的包默认放在用户目录下的.npm-global或者系统级的/usr/lib/node_modules具体在哪取决于你的 npm 配置。Claude Code 装完之后如果提示command not found八成是全局 bin 目录没进 PATH。用npm config get prefix看一下前缀路径然后把这个路径下的bin目录加到.bashrc或.zshrc里。提示不要用sudo npm install -g去装 Claude Code 这类工具。用 sudo 装会导致文件属主变成 root后续升级、配置写入都会遇到权限问题。正确做法是配置好用户级的 npm prefix然后普通权限安装。3. tmux让 AI 编程助手真正常驻的关键3.1 为什么不是 nohup也不是 screen如果你只是想让 Claude Code 在后台跑nohup 也能凑合。但一旦你需要同时管理多个会话、随时切回去看输出、在会话里再开新窗口nohup 就完全不够用了。tmux 的价值在于它把终端会话变成了一个可以命名、可以分离、可以重新附着的东西。举个实际场景你让 Claude Code 跑一个重构任务可能要十几分钟。这期间你想去干别的又不想丢掉它的输出。用 tmux你Ctrlb d分离出去该干嘛干嘛回来tmux attach -t work就接着看。更关键的是tmux 会话里的进程不会因为你关掉 SSH 连接就死掉——这对在远程服务器上跑 AI 助手的人来说是刚需。screen 也能做类似的事但 tmux 的配置更灵活、脚本化能力更强社区活跃度也更高。热词里 tmux 和 Claude Code、Codex 一起出现说明这已经是圈内的默认搭配了。3.2 一套够用的 tmux 配置不用搞太复杂下面这几条就能覆盖大部分场景。写进~/.tmux.conf# 把前缀键改成 Ctrla比默认的 Ctrlb 顺手 set -g prefix C-a unbind C-b bind C-a send-prefix # 开启鼠标支持方便滚动和选窗格 set -g mouse on # 窗口从 1 开始编号符合直觉 set -g base-index 1 setw -g pane-base-index 1 # 增大回滚缓冲AI 输出往往很长 set -g history-limit 50000改完tmux source-file ~/.tmux.conf生效。history-limit 这条特别重要Claude Code 一次输出可能几千行默认的 2000 行缓冲根本不够翻。3.3 用 tmux 组织多助手工作流我的习惯是给每个任务开一个 tmux 会话而不是给每个工具开一个。比如tmux new -s refactor # 在会话里开第一个窗口跑 Claude Code # Ctrlb c 开新窗口跑 Codex 做交叉验证 # Ctrlb n / p 在窗口间切换这样做的逻辑是同一个任务下Claude Code 和 Codex 可以互相参考输出。比如让 Claude Code 写实现让 Codex 做代码审查两个窗口并排看效率比来回切终端高得多。会话名用任务名而不是工具名是因为你关心的永远是我在做什么而不是我在用哪个工具。注意tmux 会话里的环境变量是创建时快照的。如果你在会话外更新了 PATH 或者某个 API key已经存在的会话不会自动感知。要么重开会话要么在会话里手动 source 一次配置文件。4. Claude Code 与 Codex 的装配差异4.1 两者的定位其实不一样很多人把 Claude Code 和 Codex 当成同类工具对比但用下来会发现它们的侧重点不同。Claude Code 更偏向对话式地驱动终端操作你可以让它直接执行命令、读写文件、跑测试交互感很强。Codex 则更偏向代码生成与补全在编辑器集成和批量代码处理上更顺手。这个差异直接影响了装配方式。Claude Code 对终端环境的依赖更重所以 tmux、shell 配置、命令执行权限这些要格外注意。Codex 对配置文件的格式更敏感热词里codex is ignoring 1 unrecognized configuration setting. check for typos这个报错就是典型的配置字段写错——它不会直接报错退出而是忽略掉不认识的字段导致你以为配置生效了其实没有。4.2 安装路径与验证Claude Code 通过 npm 全局安装后用claude命令启动。第一次运行会引导你完成认证。Codex 的安装方式类似但要注意它的 CLI 和桌面版是两套东西热词里codex安装 windows桌面版和codex cli同时出现说明不少人在这两者之间搞混了。CLI 版适合终端工作流桌面版适合图形化操作按需选一个就行不用都装。验证安装是否成功别只看命令能不能跑要实际发一条指令测试。比如让 Claude Code 执行echo hello看它能不能正确调用终端。这一步能提前暴露权限问题——有些系统默认不允许 CLI 工具执行 shell 命令需要你在配置里显式开启。4.3 认证环节的常见卡点热词里codex登录不上、your organization has disabled claude subscription access for claude code这类问题本质都是认证层面的。前者通常是网络或者凭证缓存的问题可以尝试清除本地凭证重新登录后者则是账号权限问题跟你本地环境无关需要从账号侧解决。我的经验是认证问题优先排查三件事凭证文件是否存在且未过期、系统时间是否准确时间偏差会导致 token 校验失败、以及是否有代理层在中间干扰。第三点尤其容易被忽略——如果你本地跑了代理去对接其他模型端点它可能会拦截本该直连的认证请求。5. 本地模型接入代理层为什么绕不开5.1 直连的局限Claude Code 和 Codex 默认对接的是官方端点。但很多人想用本地模型比如 LM Studio 跑的模型或者第三方模型DeepSeek、Qwen、GLM这时候就需要一个代理层来做协议转换。热词里claude code 调用lmstudio的本地模型、codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型说的都是这件事。为什么不能直接改配置指向本地地址因为不同模型的 API 协议不完全兼容。Claude Code 期望的是 Anthropic 风格的请求格式Codex 期望的是 OpenAI 风格的而 LM Studio 本地服务可能又是另一套。代理层的作用就是在中间做翻译把工具发出的请求转成目标模型能懂的格式再把响应转回来。5.2 cc switch 这类工具的工作逻辑cc switch是社区里比较常见的一个切换工具它的核心功能是管理多套端点配置让你能在不同模型之间快速切换。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错说明代理在处理 Codex 的/responses端点时失败了。这类问题的排查顺序是确认本地代理服务确实在运行端口没被占用确认目标模型端点可达用 curl 直接测一下检查请求格式转换是否有字段缺失尤其是 model 名称看代理日志定位是请求阶段还是响应阶段出错the gpt-5.6-sol model is not supported when using codex这个报错就是典型的模型名不匹配——你在配置里写的模型名代理或者目标端点不认识。解决方法是去目标端点的模型列表里确认准确名称别凭记忆写。5.3 本地模型接入的实操要点以 LM Studio 为例它启动本地服务后默认监听一个端口提供 OpenAI 兼容的接口。你要做的是在 LM Studio 里加载好模型启动本地服务在代理配置里把端点指向http://localhost:端口/v1把模型名填成 LM Studio 里显示的那个准确名称用 curl 先测通再让 Claude Code 或 Codex 去连这里有个容易踩的坑本地模型的上下文窗口往往比官方模型小Claude Code 发过去的请求可能超出窗口导致截断。解决办法是在代理层做请求裁剪或者换一个上下文更大的本地模型。提示本地模型接入后响应速度取决于你的硬件。如果发现卡顿严重先确认是不是模型太大跑不动而不是代理配置有问题。用top或nvidia-smi看一下资源占用就清楚了。6. 那些报错信息背后的真实原因6.1 配置字段被静默忽略codex is ignoring 1 unrecognized configuration setting. check for typos or d这条报错值得单独说。它的危险之处在于静默——工具不会因为你写错字段就崩溃而是默默忽略然后你以为是别的地方出了问题排查方向完全跑偏。我的做法是每次改完配置文件都用工具自带的配置校验命令过一遍如果有的话或者至少启动时仔细看输出。Codex 这类工具通常在启动日志里会列出它实际加载了哪些配置对照一下就知道有没有被忽略的字段。6.2 组织策略导致的访问受限your organization has disabled claude subscription access for claude code这类问题本地怎么折腾都没用因为限制在账号侧。遇到这种报错先确认你用的是个人账号还是组织账号组织账号的策略由管理员控制。如果是个人账号出现类似提示检查一下订阅状态是否正常。6.3 版本不匹配引发的连锁反应error installing 24.21.0: node.js v24.21.0 is not yet released和the gpt-5.6-sol model is not supported本质是同一类问题你引用的东西不存在。前者是版本号不存在后者是模型名不存在。这类问题的通用解法是不要凭记忆或道听途说填参数去官方源确认准确值。我见过太多人在这上面浪费时间——抄了一个教程里的版本号结果那个版本早就被撤了然后花几个小时排查为什么装不上。养成填参数前先核对的习惯能省下大量时间。7. 编辑器集成VS Code 里的装配思路7.1 为什么要在编辑器里集成终端里跑 Claude Code 和 Codex 已经能干活了但如果你大部分时间在 VS Code 里写代码来回切终端会打断心流。VS Code 的集成终端可以直接跑这些 CLI 工具配合 tmux 或者 VS Code 自带的多终端管理体验会顺很多。热词里vscode配置claude code、claude code for vs code、vscode接入claude code说的就是这个需求。7.2 集成时的注意事项VS Code 的集成终端默认继承系统的 shell 环境但有几个地方容易出问题。一是 PATHVS Code 启动时拿到的 PATH 可能和你终端里手动 source 过的不一样导致claude命令找不到。解决办法是在 VS Code 设置里显式配置终端的环境变量或者用绝对路径调用。二是终端类型。VS Code 默认可能用 PowerShell 或者 cmd而 Claude Code 的很多功能依赖 Unix 风格的 shell。在 Windows 上建议把默认终端设成 Git Bash 或 WSL否则命令执行会各种报错。三是会话持久性。VS Code 关掉窗口集成终端里的进程就没了。如果你需要长时间运行的任务还是得靠 tmux 在外部维持会话VS Code 里只是 attach 上去看。7.3 一套顺手的布局我的习惯是把 VS Code 分成三块左边代码编辑区右边上方是 Claude Code 终端右边下方是 Codex 终端。这样写代码的时候两个助手的输出都在视野里需要哪个就用哪个。VS Code 的终端分屏用CtrlShift5就能开比手动拖拽快。8. 装配完成后的日常维护8.1 升级策略Node.js、Claude Code、Codex、tmux这些组件都会更新。我的建议是分批升级不要一次全更。先更 Node.js 的补丁版本比如 20.11 到 20.12观察几天没问题再更工具本身。这样出问题时容易定位是哪个组件引起的。升级前记得备份配置文件。Claude Code 和 Codex 的配置、tmux 的配置、代理层的配置都值得存一份到版本控制里。我见过有人升级后配置被覆盖重新配了半天。8.2 日志与排查养成看日志的习惯。Claude Code 和 Codex 一般会在用户目录下留日志文件代理层也有自己的日志。出问题时先看日志比盲目试错快得多。tmux 的日志可以用pipe-pane命令导出方便事后分析。8.3 资源占用监控本地模型 多个 CLI 助手同时跑资源占用不小。定期用htop、nvidia-smi看一下避免某个进程吃满内存导致系统卡死。如果发现某个助手空闲时也占大量资源检查是不是有后台任务没结束。9. 我在实际装配中总结的几条经验搭这套环境的过程中有几个体会是文档里不会写、但实际很管用的。第一先把最小可用环境跑通再逐步加组件。不要一上来就 Node.js tmux Claude Code Codex 代理层全装上那样出问题根本不知道是哪一环。先装 Node.js跑通一个工具再加第二个再加代理每步都验证。第二配置文件用版本控制管理。~/.tmux.conf、工具的配置目录、代理配置全部纳入 git。这样换机器或者配置被改坏时一条命令就能恢复。第三报错信息要完整读不要只看关键词。很多报错的前半句才是根因后半句只是表象。比如cc switch local proxy failed while handling codex endpoint /responses重点在 local proxy failed而不是 /responses。第四本地模型和官方模型的能力差距要有预期。本地模型接入后别指望它和官方模型表现一样。上下文长度、推理能力、指令遵循度都可能有明显差距。把它当成离线可用的备选而不是完全替代。第五tmux 会话命名要有规律。我见过有人开了一堆会话名字都是默认的 0、1、2最后自己都分不清哪个是哪个。用任务名或者项目名命名tmux ls一眼就能找到。这套 openrig 式的装配思路核心不是某个具体工具而是把环境当成一个可管理、可复现、可维护的系统来对待。工具会换版本会变但这套组织方式能让你在换工具时少走很多弯路。