1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“成套装置”或者“把一堆零散部件组装成一个能干活的工作台”。放到 AI 编程助手这个场景里这个命名其实非常贴切——它想做的就是把 Claude Code、Codex 这类命令行 AI 编程工具和 Node.js、tmux 这些底层运行环境整合成一套可以随时开工的“装备架”。我接触 Claude Code 和 Codex 的时间不算短从最早的命令行版本一路用到现在最深的感受是这两个工具本身很强但它们的“周边环境”极其容易把人劝退。Node.js 版本不对、tmux 会话管理不熟、本地模型接不进来、代理配置一改就报错……这些问题单独看都不难但叠在一起就足以让一个刚上手的人卡上一整天。openrig这个项目标题背后我理解的核心诉求就是把“装环境、配工具、接模型、管会话”这一整套流程标准化、可复现化让使用者把精力放在写代码上而不是耗在环境折腾上。这篇文章我会围绕openrig这个主题结合 Claude Code、Codex、Node.js、tmux 这几个关键词把一套完整的本地 AI 编程工作台的搭建思路、核心原理、实操步骤和踩坑经验讲透。不管你是刚听说 Claude Code 想试试还是已经在用 Codex 但总被环境问题打断这篇内容都能给你一套可以直接抄作业的方案。我不会只给你命令我会告诉你每条命令背后的意图以及为什么这么设计。需要先说明一点openrig的公开资料目前非常有限项目正文和关键词都是空的所以下面的内容是我基于 Claude Code、Codex、Node.js、tmux 这套技术栈的通用实践结合大量真实使用经验做的合理推演和补全。凡是推演的部分我都会明确标注避免误导。2. 为什么是 Node.js tmux 这套组合底层选型的逻辑2.1 Node.js 在这套体系里扮演的真实角色很多人对 Node.js 的认知还停留在“写后端的 JavaScript 运行时”但在 Claude Code 和 Codex 这类工具的场景里Node.js 的角色其实是分发载体和运行时底座。这两个工具绝大多数版本都是通过 npm 包的形式分发的也就是说你机器上必须先有一个能正常工作的 Node.js 环境才能把 CLI 装起来。这里有个非常关键的细节也是热词里反复出现error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错的原因Node.js 的版本号分为“已发布稳定版”和“尚未发布/预发布版”。如果你在安装脚本里写死了一个还不存在的版本号或者用了某个镜像源还没同步的版本就会直接报这个错。我踩过这个坑当时为了追新手动指定了一个奇数版本号结果卡了半小时才反应过来是版本根本不存在。正确的做法是优先使用 LTS长期支持版本。LTS 版本经过充分测试npm 生态兼容性最好Claude Code 和 Codex 的官方文档也基本都推荐 LTS。你可以去 Node.js 官网下载页认准标着 “LTS” 的那个版本而不是标着 “Current” 的最新版。Current 版本虽然新但可能和某些依赖包存在兼容问题尤其是涉及原生模块编译的时候。安装方式上我强烈建议用版本管理工具而不是直接下安装包。原因很简单你迟早会遇到“这个项目要 Node 18那个工具要 Node 20”的情况。用nvmNode Version Manager这类工具可以在不同版本之间秒切不用反复卸载重装。在 Ubuntu 上装 nvm 就是一行脚本的事在 Windows 上可以用 nvm-windowsmacOS 上同样有对应的版本。装完之后nvm install --lts和nvm use --lts两条命令就能把环境搞定。提示安装完 Node.js 后务必用node -v和npm -v各验证一次。我见过有人只验证了 node 没验证 npm结果 npm 因为权限问题没装上后面装 CLI 时才发现白白浪费排查时间。2.2 tmux 解决的“会话持久化”痛点如果说 Node.js 是底座那 tmux 就是这套工作台的“操作台面”。tmux 是一个终端复用器它的核心价值在于会话与窗口的解耦。普通终端里你关掉窗口里面跑的进程就跟着结束了但在 tmux 里会话是独立于窗口存在的你关掉终端再重新连上之前跑的东西还在。这个特性在 AI 编程场景里太重要了。Claude Code 和 Codex 在执行任务时经常需要长时间运行——比如让它读一个大仓库、跑一轮完整的测试、或者持续监听某个文件变化。如果你直接在普通终端里跑网络一抖、窗口一关任务就断了。而放在 tmux 会话里你可以随时 detach分离去干别的事回头再 attach附着回来任务一直在跑。tmux 的另一个好处是分屏。我通常的布局是左边一个 pane 跑 Claude Code 做代码生成右边一个 pane 跑 Codex 做代码审查下面再开一个 pane 看日志或者跑测试。三个 pane 在同一个窗口里切换用快捷键就行不用在多个终端窗口之间来回 AltTab。这种“一屏三用”的效率提升用过就回不去了。tmux 的基础操作其实就几个tmux new -s work新建一个叫 work 的会话Ctrlb d分离tmux attach -t work重新附着Ctrlb %垂直分屏Ctrlb 水平分屏Ctrlb 方向键切换 pane。把这几个记住日常使用就够用了。更复杂的配置可以写进~/.tmux.conf比如改前缀键、开鼠标支持、设置状态栏样式但这些属于锦上添花不影响核心功能。2.3 为什么不是“直接开个终端就干”有人可能会问我就想用个 Claude Code为什么非得搞 Node.js 版本管理加 tmux 这么复杂直接下个安装包装上不就行了这个问题的答案取决于你的使用深度。如果你只是偶尔试一下确实怎么装都行。但如果你打算把 Claude Code 或 Codex 当成日常开发的主力工具那环境的稳定性和可复现性就是刚需。我见过太多人因为 Node 版本混乱导致 CLI 时灵时不灵也见过因为没做会话管理一个长任务跑到一半断了前面的 token 全白费。openrig这类项目存在的意义就是把这些“隐性成本”提前消化掉用一套标准化的装备架换长期的省心。3. 把 Claude Code 和 Codex 装进这套装备架3.1 Claude Code 的安装路径与常见卡点Claude Code 的安装官方推荐的方式是通过 npm 全局安装。命令本身很简单但卡点往往出在几个地方。第一个卡点是权限。在 Linux 和 macOS 上全局安装 npm 包默认会往系统目录写文件如果当前用户没有写权限就会报 EACCES 错误。解决办法有两个一是用sudo提权但我不推荐因为 sudo 装的包后续管理会很乱二是配置 npm 的全局目录到用户目录下比如npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里。第二种方式更干净后续升级、卸载都不会有权限问题。第二个卡点是网络。npm 默认的源在国内访问可能很慢甚至超时这时候可以换成国内镜像源。但要注意换源之后有些包的版本可能不是最新的如果遇到“安装的版本比预期旧”的情况先检查一下源。我一般会保留官方源作为默认只在确实慢的时候临时切换。第三个卡点是版本兼容。Claude Code 对 Node.js 版本有最低要求如果 Node 太老装上了也跑不起来。所以前面强调用 LTS 版本这里就体现价值了。装完之后用claude --version验证一下能正常输出版本号说明安装成功。关于claude code might not be available in your country这类提示我的建议是先确认自己的网络环境是否满足工具的正常使用条件如果确实无法访问就不要在这上面死磕可以转向支持本地模型或国内可访问模型的替代方案比如后面会讲到的接入 LM Studio 本地模型或者通过兼容层接入其他模型服务。3.2 Codex 的安装与配置要点Codex 的安装逻辑和 Claude Code 类似也是通过包管理器分发。但 Codex 在配置上有一个特点它对配置文件的格式比较敏感。热词里出现的codex is ignoring 1 unrecognized configuration setting. check for typos or d这个警告就是典型的配置字段写错导致的。Codex 在启动时会读取配置文件如果发现不认识的字段它不会直接报错退出而是给一个警告然后忽略。这个设计有好有坏好处是不会因为一个小笔误就完全跑不起来坏处是你以为配置生效了其实根本没生效。我的经验是每次改完 Codex 配置都要仔细看启动时的输出。如果看到 “ignoring unrecognized configuration setting” 这类提示立刻回去检查字段名拼写。常见的错误包括把model写成models、把apiKey写成api_key不同工具的大小写和分隔符规范不一样、多写了空格或者用了中文标点。这些看起来很低级但在深夜赶工的时候真的很容易犯。另一个常见问题是codex无法加载组织设置。这通常和账号权限或组织策略有关。如果你用的是团队账号可能是管理员在组织层面限制了某些功能如果是个人账号检查一下登录状态是否正常。这类问题的排查思路是先确认账号本身能正常登录再确认组织策略没有限制最后才怀疑工具本身。3.3 用 tmux 把两个工具“并排摆好”装好之后怎么把它们组织起来用就是 tmux 发挥作用的地方了。我常用的一个布局是这样的# 新建一个名为 airig 的会话 tmux new -s airig # 在会话里垂直分屏左边跑 Claude Code # 按 Ctrlb % 分屏后在左边 pane 执行 claude # 切换到右边 pane跑 Codex # 按 Ctrlb 方向键切换然后执行 codex这样左边 Claude Code 负责生成和修改代码右边 Codex 负责审查和补充两个工具各司其职。如果还需要看日志或者跑测试可以再水平分一个 pane 出来。整个工作流在一个 tmux 会话里完成关掉终端再回来一切照旧。这里有个小技巧给 tmux 会话起有意义的名字。我见过有人所有会话都叫默认的 0、1、2时间一长根本分不清哪个是哪个。用-s参数起个名字比如airig、review、debug切换的时候一目了然。查看当前有哪些会话用tmux ls切换用tmux attach -t 名字。4. 接入本地模型让这套装备架不依赖外部服务4.1 为什么要考虑本地模型Claude Code 和 Codex 默认都是连接云端模型的这对网络环境有要求。但在某些场景下接入本地模型是更优解一是隐私敏感的代码不想往外传二是网络不稳定时本地模型不受影响三是成本可控本地跑不产生按 token 计费的费用。LM Studio 是目前比较流行的本地模型运行工具它提供了图形界面可以下载和运行各种开源模型并且暴露一个兼容 OpenAI 接口的本地服务。Claude Code 和 Codex 这类工具很多都支持通过配置 base URL 的方式把请求指向本地服务。这样一来工具本身的交互逻辑不变但底层模型换成了本地跑的。4.2 配置本地模型接入的关键步骤接入的核心思路是三步启动本地模型服务、拿到服务地址、在工具里配置指向这个地址。第一步在 LM Studio 里加载一个模型然后启动本地服务器。默认情况下它会监听一个本地端口比如http://localhost:1234。你需要在 LM Studio 的服务器设置里确认这个地址和端口以及是否开启了兼容 OpenAI 的接口格式。第二步在 Claude Code 或 Codex 的配置里找到模型服务地址的配置项。不同工具的配置字段名不一样有的叫baseURL有的叫apiBase有的叫endpoint。你需要查对应工具的文档确认。配置的时候要注意地址通常要带上/v1这样的路径前缀具体取决于本地服务的接口规范。第三步验证连通性。配置完之后发一个简单的请求测试一下看工具是否能正常拿到本地模型的响应。如果报连接错误先检查本地服务是否在运行、端口是否对得上、防火墙是否拦截。如果报模型不存在检查配置里的模型名称是否和本地加载的模型名称一致。注意本地模型的上下文窗口通常比云端模型小处理大文件时可能会截断。如果你的代码仓库很大建议先用小范围测试确认模型能处理再扩大范围。4.3 本地模型和云端模型的取舍本地模型不是万能的。它的优势是隐私和稳定劣势是能力上限。开源模型在代码理解和生成上和顶级云端模型还有差距尤其是复杂重构和长上下文推理。我的建议是日常的代码补全、简单修改、格式化这类任务用本地模型完全够用遇到复杂的架构设计、跨文件重构再切回云端模型。这套装备架的价值就在于切换模型只需要改配置不用重装工具。5. 那些让人抓狂的报错排查链路与修复思路5.1 “cc switch local proxy failed” 这类代理错误的本质热词里有一个很典型的报错cc switch local proxy failed while handling codex endpoint /responses。这个报错的关键词是 “local proxy” 和 “endpoint”。它说明工具在尝试通过一个本地代理去访问 Codex 的/responses接口时失败了。这类问题的排查我一般按这个顺序走确认本地代理是否在运行。如果配置里指定了一个本地代理端口先确认那个端口上确实有服务在监听。用curl或者浏览器访问一下那个地址看有没有响应。确认 endpoint 路径是否正确。/responses这个路径是 Codex 的接口规范如果代理转发的时候路径拼错了或者多了少了斜杠就会 404。确认代理的转发规则。本地代理的作用是把请求转发到真正的服务地址如果转发目标配错了或者转发时丢了 header就会失败。看日志。代理工具一般都有日志报错的具体原因通常写在日志里比控制台输出的那行字详细得多。这里我要强调一个原则遇到代理类报错不要急着改配置先确认链路每一环是否通。从工具到代理、从代理到目标服务逐段用 curl 测试定位到具体是哪一段断了再针对性修复。盲目改配置只会让问题更乱。5.2 Node.js 版本报错的识别与处理前面提到的error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个报错的识别其实很直接版本号不存在。但为什么会出现指定一个不存在版本的情况常见原因有三个一是手动写版本号时写错了二是某个脚本里硬编码了一个未来版本三是镜像源同步延迟官方已发布但镜像还没有。处理方式先用nvm ls-remote看一下当前可用的版本列表确认你要的版本确实存在。如果不存在换一个存在的 LTS 版本。如果是镜像源问题临时切回官方源再装。装完之后用node -v确认实际生效的版本。还有一个容易混淆的点全局 Node 版本和项目级 Node 版本。如果你在项目目录下有.nvmrc或.node-version文件nvm 会自动切换到指定版本。有时候你在全局装了新版本但进入项目目录后被自动切回了旧版本导致工具跑不起来。这时候检查一下项目里的版本指定文件确认它指向的版本是你想要的。5.3 配置字段被忽略的隐蔽问题codex is ignoring 1 unrecognized configuration setting这个警告隐蔽性很强因为它不影响启动只影响功能。我遇到过一次配置里写了一个自定义的模型参数但字段名拼错了一个字母Codex 启动正常但那个参数一直没生效导致模型行为不符合预期排查了很久才发现是拼写问题。我的应对方法是把配置文件当成代码来管理。具体做法是配置文件用版本控制工具管起来每次修改都记录改了什么、为什么改。这样一旦出问题可以快速回滚到上一个可用版本也可以对比找出是哪个改动引入的问题。另外配置字段的命名规范要统一要么全用驼峰要么全用下划线不要混着来减少出错概率。5.4 组织设置无法加载的排查codex无法加载组织设置这个问题我把它归为“账号与权限”类问题。排查思路是分层的第一层账号本身。确认账号能正常登录没有过期或被封禁。第二层组织归属。确认账号所属的组织是否正确有没有被移出组织。第三层组织策略。确认组织管理员有没有限制某些功能比如禁用了某个模型或某个接口。第四层本地缓存。有时候是本地缓存的凭证过期了清除缓存重新登录能解决。这类问题的特点是工具本身的日志往往不够详细需要去账号管理后台看。所以遇到这类问题不要只在本地折腾登录后台看看账号状态往往能更快定位。6. 把工作流跑顺日常使用中的效率技巧6.1 用 tmux 脚本一键拉起整套环境每次手动开 tmux、分屏、启动工具重复几次就烦了。我的做法是写一个启动脚本把整套流程自动化。脚本的大致逻辑是检查是否已有同名会话没有就新建在会话里按预设布局分好 pane在每个 pane 里启动对应的工具。#!/bin/bash SESSIONairig # 如果会话已存在直接附着 tmux has-session -t $SESSION 2/dev/null if [ $? -eq 0 ]; then tmux attach -t $SESSION exit 0 fi # 新建会话并分屏 tmux new-session -d -s $SESSION tmux split-window -h -t $SESSION tmux split-window -v -t $SESSION # 在左侧 pane 启动 Claude Code tmux send-keys -t $SESSION:0.0 claude C-m # 在右上 pane 启动 Codex tmux send-keys -t $SESSION:0.1 codex C-m # 在右下 pane 留作日志或测试 tmux send-keys -t $SESSION:0.2 echo ready for logs C-m # 附着到会话 tmux attach -t $SESSION这个脚本可以根据自己的习惯调整比如换成水平分屏、加更多 pane、预设工作目录等。核心价值是把重复劳动变成一次执行每天开工前跑一下环境就绪。6.2 让 Claude Code 直接执行终端命令的注意事项Claude Code 有一个很实用的能力直接执行终端命令。这意味着你可以让它帮你跑测试、装依赖、查文件而不用自己手动敲。但这个能力也带来风险如果命令有破坏性执行了就收不回来。我的做法是在让工具执行命令前先看清楚它要执行什么。Claude Code 在执行命令前通常会展示命令内容并请求确认不要习惯性地一路回车。对于删除文件、修改系统配置、推送代码这类操作一定要确认清楚再放行。另外可以在配置里设置命令白名单或黑名单把危险命令挡在外面。6.3 多模型切换的配置管理当你同时用 Claude Code、Codex还接了本地模型和第三方模型时配置管理就成了一个挑战。我的经验是把不同场景的配置存成不同的文件用的时候切换。比如config.local.json对应本地模型config.cloud.json对应云端模型切换时用软链接或者环境变量指定用哪个。这样做的好处是每个配置都是独立完整的不会因为改了一个字段影响到另一个场景。而且配置文件可以纳入版本控制换机器的时候直接拉下来就能用不用重新配。7. 关于这套装备架的一些个人体会折腾 Claude Code、Codex、Node.js、tmux 这套组合的过程中我最大的体会是工具本身的能力固然重要但决定长期使用体验的往往是环境是否稳定、流程是否顺畅。一个能力稍弱但环境稳定的工具长期产出可能比一个能力很强但三天两头出问题的工具更高。openrig这个方向之所以有价值就是因为它试图把“环境稳定性”这件事工程化。虽然目前公开资料有限但沿着这个思路每个人都可以搭建属于自己的装备架。核心原则就三条版本用 LTS 不用最新、会话用 tmux 做持久化、配置用版本控制管起来。把这三条做到大部分环境问题都能提前规避。最后分享一个我踩过的坑有一次为了省事直接在系统 Python 环境里装了一堆东西后来发现和 Node.js 的某些全局包冲突排查了一整天才找到原因。从那以后我坚持环境隔离——Node 用 nvm 管Python 用虚拟环境管系统层面尽量保持干净。这个习惯看起来麻烦但省下的排查时间远超投入。