1. 从 openrig 说起一个把 Claude Code 和 Codex 装进同一台机器的实战思路第一次看到 openrig 这个名字直觉告诉我它跟“把 AI 编程工具搭起来跑通”这件事脱不了干系。事实也确实如此——openrig 本质上是一套围绕 Claude Code、Codex 这类命令行 AI 编程助手搭建的本地运行环境方案核心目标只有一个让你在一台机器上把 Claude Code 和 Codex 都装好、配好、跑起来并且能随时切换、互不干扰。为什么这件事值得单独拿出来讲因为过去大半年里我见过太多人卡在同一个地方Node.js 版本不对、tmux 会话管理混乱、Claude Code 和 Codex 的配置互相覆盖、本地模型接不进去、第三方 API 端点报错。这些问题的共同点是——它们都不是 AI 本身的问题而是“环境工程”的问题。openrig 要解决的恰恰就是这层环境工程。这篇文章适合三类人看第一类是完全没接触过 Claude Code 和 Codex想从零搭一套能用的环境第二类是用过但总在版本、配置、切换上翻车想要一套稳定的组织方式第三类是已经在用但想把本地模型、第三方 API、多工具协同整合进同一套工作流。不管你属于哪一类下面这些内容都是我从实际搭建和反复踩坑里整理出来的能直接抄作业。需要先说明一点openrig 并不是某个官方发布的软件包它更像是一种“环境组织约定”——把 Node.js、tmux、Claude Code、Codex 以及相关配置按照一套清晰的目录和会话结构管理起来。所以本文讲的不是“安装某个叫 openrig 的软件”而是“按照 openrig 的思路把整套 AI 编程环境搭稳”。2. 整体设计与思路拆解为什么是 Node.js tmux 多工具并存2.1 为什么底层一定要先搞定 Node.jsClaude Code 和 Codex 的 CLI 版本绝大多数情况下都是通过 npm 分发的。这意味着你机器上的 Node.js 版本直接决定了这两个工具能不能装、装完能不能跑。我见过最常见的翻车现场就是系统自带的 Node.js 是十几年前的版本npm 装包直接报错或者装上了但运行时报语法错误。这里有个关键判断不要用系统包管理器自带的 Node.js。Ubuntu 上apt install nodejs装出来的版本往往偏旧而且和 npm 的版本匹配经常出问题。正确做法是用 NodeSource 的源装 Node.js 20 LTS 或更高版本或者用 nvm 做版本管理。为什么强调 20因为 Claude Code 和 Codex 的依赖链里已经有用到较新的 ES 特性Node.js 18 在某些场景下会出兼容问题20 LTS 是目前最稳的基线。还有一个细节网上经常能看到error installing 24.21.0: node.js v24.21.0 is not yet released这类报错。这通常是因为你在用 nvm 装一个还不存在的版本号或者源里没有这个版本。遇到这种报错先nvm ls-remote看一下实际可用的版本列表别硬装一个不存在的版本。2.2 tmux 在这里扮演什么角色很多人第一次听说 tmux 和 AI 编程工具放一起会疑惑tmux 不是终端复用工具吗跟 Claude Code 有什么关系关系大了。Claude Code 和 Codex 都是长时间运行的交互式进程如果你直接在普通终端里跑一旦 SSH 断开、终端关闭进程就没了。更麻烦的是当你同时跑 Claude Code 和 Codex或者同时开多个项目会话时没有 tmux 你会陷入“窗口切来切去、会话找不到”的混乱。tmux 的价值在于它把每个 AI 工具会话隔离在独立的 pane 或 window 里你可以随时 detach 再 attach进程不中断。对于 openrig 这种“多工具并存”的场景tmux 几乎是必需品。我的习惯是一个 tmux session 叫ai-rig里面开三个 window——一个跑 Claude Code一个跑 Codex一个留给 shell 做辅助操作。这样切换成本极低而且不会互相干扰。2.3 多工具并存的核心矛盾配置隔离Claude Code 和 Codex 都会在用户目录下写配置比如~/.claude、~/.codex这类目录。如果你不做隔离两个工具的配置、缓存、会话历史会混在一起出问题时根本分不清是谁的锅。openrig 思路里最重要的一条就是每个工具用独立的配置目录通过环境变量或启动参数指定而不是让它们都往默认位置写。具体怎么做Claude Code 支持通过环境变量指定配置路径Codex 也有类似的机制。你可以在启动脚本里为每个工具设置不同的HOME子目录或者用工具自身支持的配置路径参数。这样即使你同时跑两个工具、接不同的模型端点也不会出现“Codex 读到了 Claude Code 的配置”这种诡异问题。2.4 方案选型对比为什么不用 Docker 一把梭有人会问既然要隔离为什么不直接上 Docker每个工具一个容器我的实测结论是Docker 适合做“干净复现”但不适合做“日常高频使用”。原因有三第一AI 编程工具需要频繁访问你的项目目录Docker 的卷挂载在文件监听、热重载场景下经常出问题第二tmux 会话在容器里管理起来更绕第三本地模型调用比如接 LM Studio涉及网络端点容器网络配置又是一层额外成本。所以 openrig 的思路是“轻隔离”用 Node.js 版本管理 独立配置目录 tmux 会话隔离达到够用的隔离度同时保留直接访问本地文件和网络的便利。这套方案在 Ubuntu 和 macOS 上都验证过Windows 上建议用 WSL2原生 Windows 的终端环境跑这套组合会有各种边角问题。3. 核心细节解析与实操要点从零把环境搭稳3.1 Node.js 20 的安装与版本锁定在 Ubuntu 上我推荐用 NodeSource 源安装步骤清晰且版本可控。先更新包索引然后添加 NodeSource 的 20.x 源再安装。装完之后用node -v和npm -v确认版本。如果你需要多版本共存nvm 是更好的选择但要注意 nvm 装完后要重新加载 shell 配置否则node命令找不到。这里有个实操心得装完 Node.js 后先跑一次npm config get registry确认 registry 是你期望的源。有些环境下默认 registry 访问慢会导致 Claude Code 和 Codex 安装过程卡住甚至超时。如果慢换成国内可访问的镜像源安装速度会明显提升。另一个坑是权限问题。如果你用sudo npm install -g装全局包可能会遇到权限报错或者装到了系统目录。更好的做法是配置 npm 的全局目录到用户目录下这样不需要 sudo 也能装全局 CLI 工具。具体就是设置npm config set prefix到你自己的目录然后把该目录的 bin 加进 PATH。3.2 Claude Code 的安装与配置要点Claude Code 的安装本身不复杂npm 全局装即可。真正容易出问题的是配置环节。第一认证方式要选对不同版本对认证的要求不一样装完后先跑一次帮助命令确认可用参数。第二如果你要用本地模型或第三方端点需要配置对应的 base URL 和模型名这里最容易出现“模型不支持”的报错比如the gpt-5.6-sol model is not supported这类本质是你填的模型名和端点实际支持的模型对不上。我的建议是先用官方默认配置跑通一次确认工具本身没问题再去改端点和模型。这样出问题时能快速定位是“工具没装好”还是“端点配错了”。另外Claude Code 在 VS Code 里有对应的扩展如果你习惯在编辑器里用装扩展后在设置里指定 CLI 路径即可但要注意扩展和 CLI 的版本匹配版本差太多会出现调用失败。3.3 Codex 的安装与常见报错处理Codex 的安装同样走 npm但它的配置项更多也更容易出“配置被忽略”的问题。比如codex is ignoring 1 unrecognized configuration setting这个报错意思是你的配置文件里有一个它不认识的键。这不一定是致命错误但说明你的配置格式或键名有问题最好对照官方文档把键名改对否则你以为生效的配置其实没生效。Codex 登录不上是另一个高频问题。常见原因有三个认证信息过期、网络端点不可达、配置目录权限不对。排查顺序建议是先确认配置文件路径正确再确认认证信息有效最后确认端点可达。如果报your organization has disabled claude subscription access这类信息说明是账号层面的权限问题不是本地环境问题这种情况换认证方式或换账号才能解决。3.4 tmux 会话组织与工具切换tmux 的配置不需要太复杂但几个关键设置能大幅提升体验。第一把 prefix 键改成你顺手的组合默认的 Ctrlb 在频繁切换时有点别扭。第二开启鼠标支持方便直接点选 pane。第三设置合理的窗口和 pane 命名让你一眼看出哪个是 Claude Code、哪个是 Codex。我的实际组织方式是创建一个名为ai-rig的 sessionwindow 0 叫claudewindow 1 叫codexwindow 2 叫shell。每个 window 里跑对应的工具。切换用prefix 数字detach 用prefix d重新 attach 用tmux attach -t ai-rig。这套流程跑熟之后你几乎感觉不到 tmux 的存在但它在你 SSH 断开时救过你无数次。3.5 配置隔离的具体落地方式配置隔离的核心是让每个工具读自己的配置目录。Claude Code 和 Codex 都支持通过环境变量或启动参数指定配置路径。你可以在启动脚本里为每个工具 export 不同的配置目录变量然后再启动工具。这样即使两个工具同时运行也不会互相读写对方的配置。具体操作上我建议在项目根目录下建一个rig/目录里面分claude-config/和codex-config/启动脚本里分别指向这两个目录。这样做的好处是配置跟着项目走换项目时配置不会串。缺点是每个项目都要初始化一次但对于需要严格隔离的场景这点成本完全值得。4. 实操过程与核心环节实现一步步把 openrig 跑起来4.1 环境准备与依赖安装的完整流程先把基础环境准备好。Ubuntu 上先更新系统包索引然后安装 tmux 和 curl 这些基础工具。接着装 Node.js 20 LTS装完确认版本。然后配置 npm 的全局目录和 registry。这几步做完基础环境就算就绪了。具体命令层面更新索引用sudo apt update装 tmux 用sudo apt install tmux装 Node.js 用 NodeSource 的脚本。装完 Node.js 后设置 npm prefix 到用户目录再把该目录的 bin 加进 PATH。这些步骤看起来琐碎但每一步都有明确的验证方式node -v看版本npm -v看 npm 版本tmux -V看 tmux 版本echo $PATH确认路径生效。这里有个细节容易被忽略装完 Node.js 后当前 shell 的 PATH 可能还没更新需要source一下配置文件或者重开终端。如果你发现node命令找不到先检查 PATH别急着重装。4.2 Claude Code 与 Codex 的安装与首次运行Node.js 就绪后用 npm 全局安装 Claude Code 和 Codex。安装命令本身很简单关键是装完后要验证。先跑claude --version和codex --version确认安装成功再跑一次帮助命令看可用参数。如果版本命令报错大概率是 Node.js 版本或 PATH 问题回到上一步排查。首次运行时工具会引导你做认证或配置。这时候建议先用默认配置跑通确认工具能正常响应再去改端点和模型。我见过太多人一上来就改配置结果工具跑不起来分不清是安装问题还是配置问题。先用默认配置跑通等于给自己留了一个“已知可用”的基线后续出问题可以对比排查。4.3 tmux 会话的创建与工具启动脚本tmux 会话的创建可以手动做也可以写成脚本。手动做就是tmux new -s ai-rig然后Ctrlb c创建新 windowCtrlb ,重命名 window在每个 window 里启动对应工具。写成脚本的话可以用tmux new-session -d -s ai-rig创建后台会话再用tmux send-keys往各个 window 里发启动命令。我的习惯是写一个start-rig.sh脚本里面按顺序创建 session、window并在每个 window 里启动对应工具。这样每次开机或重连后跑一次脚本就能恢复整个工作环境。脚本里要注意的是启动工具前先 cd 到项目目录并 export 对应的配置目录变量确保工具读到正确的配置。4.4 本地模型与第三方端点的接入配置接入本地模型比如 LM Studio或第三方端点时核心是配置 base URL 和模型名。base URL 要指向你的本地服务地址模型名要和服务实际加载的模型一致。这里最常见的错误是模型名写错导致工具报“模型不支持”。排查方法很简单先用 curl 直接请求你的端点确认端点可用且返回的模型列表里有你写的模型名。第三方端点的接入逻辑类似但要注意认证方式。有些端点用 API Key有些用其他认证机制配置时要看清楚。另外端点的响应格式要和工具期望的格式匹配否则会出现“请求发出去了但解析失败”的情况。遇到这种问题先用 curl 看原始响应再对比工具期望的格式基本能定位问题。4.5 多工具协同的实际工作流环境搭好后实际工作流是这样的SSH 连上机器tmux attach -t ai-rig切到 claude window 用 Claude Code 做代码分析和生成切到 codex window 用 Codex 做另一类任务切到 shell window 做 git 操作和文件管理。三个 window 互不干扰配置各自独立模型端点也可以不同。这套工作流的优势在于你不需要反复启动和关闭工具会话一直保持你可以在两个工具之间快速切换对比它们的输出你的配置和会话历史都隔离在各自目录里出问题时排查范围明确。实测下来这套流程比“每次用的时候现开终端”效率高很多尤其是在需要长时间迭代的任务上。5. 常见问题与排查技巧实录那些我踩过的坑5.1 安装阶段的典型报错与解决安装阶段最常见的报错是 Node.js 版本问题。error installing 24.21.0: node.js v24.21.0 is not yet released这类报错本质是你指定的版本不存在。解决方法是先查可用版本列表再装一个实际存在的版本。另一个常见报错是 npm 权限问题表现为EACCES错误解决方法是配置 npm prefix 到用户目录避免用 sudo 装全局包。还有一个容易被忽略的点网络问题导致的安装超时。如果你在国内网络环境下装包很慢换 registry 镜像能明显改善。但要注意换镜像后有些包的版本可能和官方源有差异装完后最好验证一下版本是否符合预期。5.2 配置阶段的报错与排查思路配置阶段最典型的报错是“配置被忽略”比如codex is ignoring 1 unrecognized configuration setting。这说明你的配置文件里有工具不认识的键。解决方法是查官方文档确认正确的键名或者先用最小配置跑通再逐步加配置项。另一个典型报错是“模型不支持”比如the gpt-5.6-sol model is not supported这说明你填的模型名和端点实际支持的模型不匹配需要核对模型名。排查配置问题的通用思路是先用最小配置跑通确认工具本身可用再逐步加配置项每加一项验证一次出问题时对比“加了什么”和“报了什么错”基本能定位到具体配置项。5.3 运行阶段的会话与进程问题运行阶段最常见的问题是会话丢失。如果你没用 tmuxSSH 一断进程就没了。用了 tmux 之后这个问题基本消失但要注意 tmux server 本身也可能因为系统重启而终止。解决方法是把 tmux 会话的恢复写进启动脚本系统重启后跑一次脚本就能恢复。另一个问题是进程卡死。AI 工具在等待网络响应时可能长时间无响应这时候你需要能快速判断是“在等”还是“卡死了”。我的方法是看 tmux pane 的输出有没有更新如果长时间没更新就手动中断再重试。tmux 的好处是你可以随时开一个新 pane 做排查不影响原来的会话。5.4 常见问题速查表问题现象可能原因排查方向解决方式安装时报版本不存在指定了不存在的 Node.js 版本查可用版本列表装实际存在的版本npm 装包报 EACCES全局目录权限不足检查 npm prefix配置 prefix 到用户目录工具报模型不支持模型名与端点不匹配curl 端点看模型列表改成端点支持的模型名配置被忽略配置键名错误对照官方文档修正键名或删掉无效项登录不上认证过期或端点不可达检查认证和网络更新认证或换端点会话丢失没用 tmux 或 tmux 终止检查 tmux 状态用 tmux 并写恢复脚本进程卡死网络等待或工具异常看 pane 输出中断重试或换端点5.5 独家避坑技巧汇总第一个技巧装完任何工具后先跑一次版本命令和帮助命令确认工具本身可用再去改配置。这个习惯能帮你把“安装问题”和“配置问题”分开排查效率翻倍。第二个技巧配置文件改动前先备份。AI 工具的配置项多改错一个键可能导致工具完全跑不起来。备份之后出问题可以快速回滚到已知可用状态。第三个技巧tmux 会话命名要有规律。我见过有人开了十几个 session 名字都是默认的最后自己都分不清哪个是哪个。用ai-rig-claude、ai-rig-codex这种命名一眼就能看出用途。第四个技巧本地模型端点先用 curl 验证。很多人配完端点直接启动工具报错了才去查端点。先用 curl 请求一次确认端点返回正常再配到工具里能省掉大量排查时间。第五个技巧Node.js 版本用 LTS别追最新。最新版可能有兼容问题LTS 版本经过更多验证稳定性更好。Claude Code 和 Codex 这类工具对 Node.js 版本有要求用 LTS 能避开大部分版本坑。6. 工具选型与扩展思路openrig 还能怎么玩6.1 为什么选 CLI 而不是纯编辑器插件Claude Code 和 Codex 都有编辑器插件版本但 openrig 思路更偏向 CLI。原因在于 CLI 的可组合性更强你可以用 tmux 管理会话可以用脚本自动化启动可以把输出重定向到文件可以和其他命令行工具管道组合。编辑器插件虽然上手快但在自动化和多工具协同上受限。当然这不是说插件不能用。如果你主要在编辑器里工作插件版本体验更顺滑。但如果你想搭一套可复用、可脚本化、可远程使用的环境CLI 是更好的基础。6.2 多模型端点的切换策略openrig 环境搭好后你可以很方便地在不同模型端点之间切换。比如 Claude Code 接一个端点Codex 接另一个端点或者同一个工具在不同项目里接不同端点。切换的核心是配置隔离——每个项目或每个会话用独立的配置目录启动时指定对应目录即可。这种切换策略的价值在于你可以根据任务类型选择最合适的模型而不必被单一端点绑定。比如代码生成用一个端点代码审查用另一个端点两者互不影响。6.3 后续可扩展的方向这套环境搭好后还有几个可扩展方向。第一把启动脚本做成 systemd 服务或开机自启省去每次手动恢复会话的步骤。第二把常用配置做成模板新项目初始化时直接复制模板减少重复配置。第三把工具输出接入日志系统方便回溯和审计。第四如果有多个机器可以把配置目录同步保持环境一致。这些扩展不是必须的但如果你长期用这套环境逐步加上这些能明显提升效率。我的建议是先把基础环境跑稳再按需扩展别一上来就追求大而全。6.4 我个人的使用体会这套 openrig 思路我用了几个月最大的感受是“稳定压倒一切”。AI 编程工具本身更新快配置项经常变如果没有一套稳定的环境组织方式你会把大量时间花在修环境上而不是写代码上。Node.js 版本锁定、tmux 会话隔离、配置目录分离这三件事做好环境问题能减少八成。另一个体会是别怕麻烦该隔离就隔离。一开始我也觉得配置隔离麻烦但经历过几次“两个工具配置串了、排查半天”之后我彻底转向了严格隔离。前期多花十分钟配置后期省下的是几小时的排查时间。最后分享一个小技巧把常用的排查命令写成 alias 或脚本比如一键检查 Node.js 版本、npm registry、tmux 会话状态、端点可达性。出问题时跑一次检查脚本基本能定位到问题环节。这个习惯让我在环境出问题时从“一脸懵”变成“三分钟定位”。