1. 从“openrig”说起一个把终端 AI 编码工具串起来的轻量方案第一次看到openrig这个名字我下意识把它拆成了 “open” 和 “rig” 两部分。rig 在工程语境里常指“把一堆零散部件搭成一套能干活的工作台”比如矿机机架、测试台架。放到 AI 编码工具这个场景里openrig 要解决的事情就很清楚了把 Claude Code、Codex 这类终端里的 AI 编码助手和 Node.js、tmux 这些底层运行环境组装成一套开箱即用、可切换、可复现的本地工作台。我接触 Claude Code 和 Codex 的时间不算短踩过的坑也足够多。最开始是在一台 Ubuntu 开发机上装 Claude Code结果卡在 Node.js 版本上后来换 Windows又遇到 Codex 登录后提示组织设置无法加载再后来想同时跑 Claude Code 和 Codex两个工具抢终端、抢会话来回切换非常难受。openrig 这类方案的价值恰恰在于它不追求做一个大而全的 GUI而是用脚本和配置把“环境准备—工具安装—模型接入—会话管理”这条链路固化下来让每次换机器、换项目都能快速复现。这篇文章适合三类人看第一类是刚听说 Claude Code、Codex想在自己电脑上跑起来但被 Node.js、环境变量、API 配置绕晕的新手第二类是已经在用但被多工具切换、会话丢失、模型接入不稳定困扰的中级用户第三类是想把这套东西沉淀成团队内部规范让同事照着抄作业就能用的工程负责人。我会围绕 openrig 这个核心思路把 Node.js 环境、Claude Code 与 Codex 的安装配置、tmux 会话管理、本地模型与第三方 API 接入、常见报错排查这几块讲透尽量做到你看完就能动手复现。需要先说明一点openrig 本身并不是一个官方大厂产品更像是一种“工作台搭建思路”的统称。不同人手里的 openrig 可能是一组 shell 脚本也可能是一个带配置文件的目录结构。所以下面讲的内容是基于我实际搭建和使用这类工作台的经验结合 Claude Code、Codex、Node.js、tmux 这些热词背后的真实需求给出的一套可落地方法。你完全可以根据自己的系统环境做裁剪。2. 整体设计思路为什么是 Node.js tmux 多工具并存2.1 核心诉求拆解不是装一个工具而是搭一套工作流很多人一开始把问题想简单了觉得“装个 Claude Code 而已npm 一行命令不就完了”。真正动手才发现问题从来不是单个工具的安装而是工具之间的协作关系。我总结下来openrig 这类工作台要同时满足四个诉求。第一是环境一致性。Claude Code 和 Codex 都是基于 Node.js 生态分发的命令行工具对 Node.js 版本有要求。你在这台机器上用 Node 20 跑得好好的换到另一台默认 Node 16 的机器上就可能报错。openrig 的第一层价值就是把 Node.js 版本这件事固定下来。第二是多工具并存。Claude Code 和 Codex 各有擅长场景有人喜欢 Claude Code 的终端命令直接执行能力有人习惯 Codex 的交互方式。让它们共存而不是互相覆盖需要合理的安装路径和配置隔离。第三是会话可保持。AI 编码助手经常要跑长任务比如让它读一个大仓库、连续改多个文件。如果终端一关会话就断体验会非常差。tmux 在这里的作用就是让会话脱离终端窗口独立存活你随时可以 attach 回去看进度。第四是模型可切换。不管是接入官方服务还是通过第三方 API 接入 DeepSeek、Qwen、GLM 这类模型配置都应该是可切换、可回滚的。openrig 的配置层要能承载这种切换需求。把这四点想清楚整个工作台的设计方向就明确了底层用 Node.js 保证运行时中间层用统一的安装目录和配置管理承载多个工具上层用 tmux 管理会话最外层用一份可读的配置说明把模型接入方式固化下来。2.2 为什么选 Node.js 作为统一运行时Claude Code 和 Codex 的 CLI 版本都依赖 Node.js这是绕不开的。但 Node.js 的版本管理本身就是一个坑。我见过太多人直接去 Node.js 官网下载一个 LTS 安装包装完发现版本不对又去下另一个版本最后系统里堆了好几个 Nodewhich node出来的路径自己都说不清。我的建议是不要用系统包管理器装 Node.js也不要用官网安装包直接覆盖而是用版本管理工具。在 macOS 和 Linux 上nvm是最成熟的选择Windows 上可以用nvm-windows或者fnm。这样做的好处是你可以为 openrig 单独指定一个 Node 版本比如nvm use 20不影响系统里其他项目。这里有个细节值得展开。热词里出现过 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available” 这类报错本质上是版本号写错了或者该版本还没正式发布。Node.js 的版本号是严格语义化的偶数大版本是 LTS奇数大版本是 Current。生产环境和工作台搭建我强烈建议锁定 LTS 版本比如 20.x 或 22.x不要追最新的 Current 版本。Current 版本虽然新特性多但生态兼容性没经过充分验证AI 编码工具这类依赖大量第三方包的东西跑在 Current 上出问题的概率明显更高。具体操作上安装 nvm 之后执行nvm install 20和nvm alias default 20把默认版本固定住。然后在 openrig 的启动脚本里显式写一句nvm use 20确保每次进入工作台环境时 Node 版本都是对的。这一步看起来简单但能省掉后面至少一半的“玄学报错”。2.3 tmux 在 openrig 里的真实定位tmux 经常被当成“终端分屏工具”但在 openrig 这套工作流里它的核心价值是会话持久化分屏只是附赠功能。设想一个典型场景你让 Claude Code 帮你重构一个模块它需要读十几个文件、跑几次测试整个过程可能十几分钟。如果你直接在普通终端里跑中途不小心关了窗口或者网络断了一下 SSH 连接任务就中断了前面的上下文也丢了。用 tmux 的话你tmux new -s claude-work建一个会话在里面跑任务然后Ctrlb ddetach 出来任务继续在后台跑。过一会儿tmux attach -t claude-work回去看一切都在。对于同时使用 Claude Code 和 Codex 的人来说tmux 还能做会话隔离。开两个窗口一个跑 Claude Code一个跑 Codex互不干扰。再配合 tmux 的窗口命名tmux rename-window claude、tmux rename-window codex切换起来一目了然。我自己的习惯是给 openrig 配一个 tmux 启动脚本一次性建好会话和窗口布局左边一个大窗口跑 Claude Code右边上下分两个小窗口一个跑 Codex一个留作普通 shell 用来查日志、跑 git 命令。这样每天开工只需要执行一个脚本工作环境就绪。2.4 多工具共存的目录结构设计openrig 要承载多个工具目录结构必须清晰否则时间一长自己都找不到东西。我推荐的结构是这样的~/openrig/ ├── bin/ # 自定义启动脚本 │ ├── start-claude │ ├── start-codex │ └── start-workbench ├── config/ # 各工具的配置文件 │ ├── claude/ │ ├── codex/ │ └── models/ ├── logs/ # 运行日志 ├── workspace/ # 实际干活的代码仓库 └── README.md # 环境说明和恢复步骤这个结构的关键在于配置和代码分离。config/放工具配置workspace/放项目代码两者互不干扰。这样你备份 openrig 的时候只需要备份config/和bin/代码仓库该用 git 管理就用 git 管理。README.md尤其重要把你机器上的 Node 版本、工具版本、模型接入方式都记下来换机器或者重装系统时照着恢复能省大量时间。3. 核心细节解析Claude Code 与 Codex 的安装配置要点3.1 Claude Code 安装从 Node.js 到首次运行Claude Code 的安装本身不复杂复杂的是前置环境和后续配置。我按顺序拆开讲。第一步确认 Node.js 版本。执行node -v确保输出是 20.x 或 22.x 这类 LTS 版本。如果版本不对先回到上一节用 nvm 切换。这一步没做好后面安装大概率报错。第二步安装 Claude Code。官方推荐的方式是通过 npm 全局安装。执行npm install -g anthropic-ai/claude-code等待安装完成。安装过程中如果出现权限报错在 macOS 和 Linux 上不要直接加sudo而是先配置 npm 的全局目录到用户目录下避免污染系统目录。具体做法是npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里。第三步验证安装。执行claude --version能输出版本号就说明安装成功。如果提示 command not found八成是 PATH 没配好检查一下 npm 全局 bin 目录是否在 PATH 里。第四步首次运行和认证。直接执行claude它会引导你完成认证流程。这里有个常见问题热词里出现过 “your organization has disabled claude subscription access for claude code” 这类提示意思是你的账号所属组织关闭了 Claude Code 的订阅访问权限。遇到这种情况要么联系组织管理员开通要么换一个个人账号。这不是安装问题是账号权限问题别在安装步骤上浪费时间。第五步配置工作目录。Claude Code 默认在当前目录下工作我建议在 openrig 的workspace/下建项目目录然后在那里启动 Claude Code。这样它的上下文和文件操作都限制在项目范围内不会误操作到其他目录。3.2 Codex 安装Windows 与 Ubuntu 的差异处理Codex 的安装在不同系统上差异比较明显我分开说。在 Ubuntu 上流程和 Claude Code 类似先确保 Node.js 版本正确然后通过 npm 安装。安装完成后执行codex --version验证。Ubuntu 上比较容易遇到的问题是和系统自带的 Node.js 冲突如果你之前用apt install nodejs装过可能会出现两个 Node 版本打架。解决办法是卸载系统版本统一用 nvm 管理。在 Windows 上情况复杂一些。热词里 “codex安装 windows桌面版” 和 “codex安装包” 说明很多人卡在 Windows 安装上。我的建议是Windows 上优先用 WSL2在 WSL 的 Ubuntu 环境里按 Linux 的方式装体验和原生 Linux 基本一致。如果一定要在 Windows 原生环境装注意两点一是 Node.js 要用 Windows 版的 nvm-windows 管理二是路径里不要有中文和空格否则 npm 安装时容易出问题。安装完成后Codex 首次运行需要登录。热词里 “codex登录” 和 “codex无法加载组织设置” 是两个高频问题。登录失败通常是网络或者账号状态问题先确认账号能正常访问服务再检查本地时间是否准确时间偏差过大会导致认证失败。组织设置加载失败多半是账号权限或者配置缓存问题可以尝试清除本地配置目录后重新登录。3.3 配置文件管理让模型切换变得可控Claude Code 和 Codex 都支持通过配置文件指定模型和 API 端点。openrig 的配置层要做的就是把这些配置集中管理方便切换。以接入第三方 API 为例热词里提到 “使用cc switch 接入 deepseek v4, qwen, glm等模型” 和 “codex接入deepseek”说明很多人有接入国产模型的需求。这类接入的核心是配置 API 端点和密钥。我的做法是在config/models/下为每个模型建一个配置文件比如deepseek.env、qwen.env里面写好端点、模型名、密钥引用。启动脚本根据参数加载对应的配置文件再启动 Claude Code 或 Codex。这样做的好处是切换模型只需要改一个启动参数不用手动改工具本身的配置。而且密钥不直接写在工具配置里而是通过环境变量注入安全性更好。这里要提醒一句密钥千万不要提交到 git 仓库config/目录要么加进.gitignore要么用单独的密钥管理方式。3.4 实操心得安装阶段最容易踩的三个坑第一个坑是Node.js 版本混乱。系统里同时存在 apt 装的 Node、官网安装包装的 Node、nvm 管理的 Nodewhich node出来的路径和你以为的不一样。解决办法是彻底清理只保留 nvm 一套。第二个坑是全局安装权限问题。在 Linux 和 macOS 上直接用sudo npm install -g装出来的包权限是 root后续更新和卸载都麻烦。正确做法是配置用户级 npm 全局目录。第三个坑是网络导致的安装失败。npm 安装过程中如果卡住或者报超时先检查网络再考虑换 npm 镜像源。国内用户可以把 npm registry 换成国内镜像安装速度会快很多。但要注意换源之后某些包的版本可能和官方源有差异遇到奇怪问题时可以换回官方源试试。4. 实操过程从零搭建一套可复用的 openrig 工作台4.1 环境准备Node.js 与 tmux 的安装配置先处理 Node.js。以 Ubuntu 为例安装 nvm 的命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新加载 shell 配置然后nvm install 20、nvm alias default 20。验证一下node -v输出 v20.xnpm -v能输出版本号。再装 tmux。Ubuntu 上sudo apt install tmuxmacOS 上brew install tmux。装完执行tmux -V验证。tmux 的配置我建议至少改两处把前缀键从默认的Ctrlb改成Ctrla如果你习惯 screen 的话以及开启鼠标支持方便滚动和选择窗口。配置文件放在~/.tmux.conf。Windows 用户如果走 WSL2 路线在 WSL 里按 Ubuntu 的方式操作即可。WSL2 的 tmux 和原生 Linux 体验一致唯一要注意的是 WSL 的终端和 Windows 终端之间的复制粘贴建议在 Windows Terminal 里配置好快捷键。4.2 工具安装Claude Code 与 Codex 的落地步骤环境就绪后开始装工具。先建好 openrig 目录结构然后依次安装。安装 Claude Codenpm install -g anthropic-ai/claude-code claude --version安装 Codexnpm install -g openai/codex codex --version两个都装完后分别在workspace/下建一个测试项目目录进去跑一次确认能正常启动和认证。这一步不要跳过很多人装完不测试等到真正干活时才发现问题那时候排查成本更高。4.3 会话管理用 tmux 固化日常工作流工具装好后写一个 tmux 启动脚本把日常会话布局固化下来。脚本逻辑大致是检查是否已有同名会话没有就新建新建后按预设布局分窗口在每个窗口里启动对应工具。#!/bin/bash SESSIONopenrig tmux has-session -t $SESSION 2/dev/null if [ $? ! 0 ]; then tmux new-session -d -s $SESSION -n claude tmux send-keys -t $SESSION:claude cd ~/openrig/workspace claude C-m tmux new-window -t $SESSION -n codex tmux send-keys -t $SESSION:codex cd ~/openrig/workspace codex C-m tmux new-window -t $SESSION -n shell tmux send-keys -t $SESSION:shell cd ~/openrig/workspace C-m fi tmux attach -t $SESSION这个脚本每次执行都会 attach 到已有会话不会重复创建。三个窗口分别跑 Claude Code、Codex 和普通 shell切换用Ctrlb加窗口号。实际用下来这套布局能覆盖九成以上的日常场景。4.4 模型接入本地模型与第三方 API 的配置方法模型接入是 openrig 里最灵活也最容易出问题的部分。我分两种场景说。第一种是接入本地模型比如热词里提到的 “claude code 调用 lmstudio的本地模型”。LM Studio 这类工具会在本地起一个兼容 OpenAI 接口的服务Claude Code 和 Codex 通过配置 API 端点指向本地服务即可。关键配置项是 base URL通常形如http://localhost:1234/v1以及模型名称。本地模型的好处是数据不出本机适合处理敏感代码缺点是性能和上下文长度受本机硬件限制。第二种是接入第三方 API比如 DeepSeek、Qwen、GLM。这类接入需要 API 密钥和端点地址。我的做法是把这些配置写成环境变量文件启动工具前 source 一下。比如export OPENAI_BASE_URLhttps://api.example.com/v1 export OPENAI_API_KEYyour-key-here然后在启动脚本里根据参数选择加载哪个配置文件。这样切换模型就是换一个文件的事。这里有个经验接入第三方 API 时先用小请求验证连通性不要一上来就跑大任务。可以用 curl 直接请求一下端点确认返回正常再启动工具。这样能把网络问题和工具配置问题分开排查。4.5 实操现场记录一次完整的搭建过程我最近一次搭建是在一台新的 Ubuntu 22.04 机器上记录一下关键节点。系统装好后先装 nvm再装 Node 20。然后装 tmux配置好.tmux.conf。接着建 openrig 目录装 Claude Code 和 Codex。两个工具都装完后分别跑了一次认证。Claude Code 认证顺利Codex 第一次登录时报了组织设置加载失败清除本地配置目录后重新登录解决。然后写 tmux 启动脚本测试会话创建和 attach。最后配置模型接入先测了官方服务再测了一个第三方 API 端点。整个流程从零到可用大约花了四十分钟其中一半时间花在排查 Codex 登录问题上。如果提前知道清除配置目录这个操作时间能压缩到二十分钟以内。5. 常见问题与排查技巧实录5.1 安装类问题速查问题现象可能原因排查方向node.js v24.21.0 is not yet released版本号错误或未发布改用 LTS 版本如 20.x安装时权限报错npm 全局目录权限问题配置用户级 npm prefixcommand not foundPATH 未包含 npm 全局 bin检查并配置 PATH安装卡住或超时网络问题检查网络考虑换镜像源Windows 路径报错路径含中文或空格改用纯英文无空格路径5.2 登录与认证类问题Codex 登录失败和组织设置加载失败是高频问题。我的排查顺序是先确认账号状态正常再检查本地时间是否准确然后清除本地配置缓存重新登录。如果还不行换一个网络环境试试。Claude Code 的订阅访问权限问题属于账号层面的限制本地怎么折腾都没用直接找账号管理员。5.3 模型接入类问题接入第三方 API 时最常见的问题是端点地址写错、密钥无效、模型名不匹配。排查方法是先用 curl 直接请求端点确认服务可达再检查密钥是否过期最后确认模型名和端点支持的模型列表一致。本地模型接入还要注意服务是否真的在监听以及端口是否被占用。5.4 会话管理类问题tmux 会话丢失通常是因为机器重启或者 tmux server 被 kill。养成习惯重要任务跑在 tmux 里定期检查会话状态。如果 tmux 会话里的工具卡死不要直接关窗口先尝试在会话里CtrlC中断再重新执行。实在不行再 kill 会话重建。5.5 独家避坑技巧第一个技巧给 openrig 写一个健康检查脚本每次开工前跑一下检查 Node 版本、工具版本、tmux 会话状态、模型端点连通性。有问题提前发现别等干活到一半才报错。第二个技巧配置文件版本化。把config/目录用 git 管理起来每次改配置都提交出问题可以回滚。密钥用环境变量或者单独的密钥文件不提交。第三个技巧日志集中存放。把 Claude Code 和 Codex 的运行日志都重定向到logs/目录按日期命名。排查问题时直接看日志比在终端里翻历史输出高效得多。6. 关于 openrig 后续可以怎么扩展这套工作台搭好之后扩展空间其实很大。我目前在做的一个方向是把常用任务脚本化比如“让 Claude Code 检查当前仓库的代码风格”“让 Codex 生成某个模块的单元测试”把这些操作写成脚本通过 tmux send-keys 注入到对应窗口执行。这样日常重复性工作可以一键触发。另一个方向是多机器同步。把 openrig 的配置目录放在同步盘或者私有 git 仓库里换机器时拉下来就能用。配合健康检查脚本新机器上几分钟就能恢复完整工作环境。还有一个方向是接入更多模型。现在 Claude Code 和 Codex 支持自定义端点理论上任何兼容 OpenAI 接口的模型都能接进来。我试过接本地模型和几个第三方 API切换起来还算顺畅。后续如果出现新的编码工具只要它支持命令行和自定义端点也能纳入 openrig 的管理范围。我个人在实际操作中的体会是openrig 这类工作台的价值不在于技术多高深而在于把琐碎的环境问题一次性解决掉让注意力回到编码本身。搭的时候多花点时间把配置和脚本写清楚后面每天都能省下折腾环境的时间。最后再分享一个小技巧把搭建过程写成 README包括每一步的命令和遇到的坑下次重装或者帮同事搭的时候直接照着走效率会高很多。