openrig：统一装配Claude Code与Codex的AI编程环境实践

1. 从 openrig 说起一个把 Claude Code 和 Codex 装进同一副骨架的思路第一次看到 openrig 这个名字我下意识把它拆成了 open 和 rig 两截。rig 在工程语境里是“装配架、机架”的意思比如测试台架、摄像机机架。所以 openrig 直译过来就是“开放的装配架”。结合它周边冒出来的 Claude Code、Codex、Node.js、tmux 这几个热搜词我基本能判断出它想干的事把当下最主流的两个终端 AI 编程助手塞进一个统一、可复用、可切换的运行骨架里让它们共享同一套环境、同一套会话管理、同一套模型接入方式。这个判断不是拍脑袋。你去看那串热词就明白了claude code 安装、codex 安装、node.js 安装、tmux、cc switch local proxy failed、codex 接入 deepseek、claude code 调用 lmstudio 的本地模型、vscode 配置 claude code……这些词几乎覆盖了一个开发者从零开始搭建 AI 编程环境的完整链路。而 openrig 要解决的正是这条链路里最烦人的部分——环境割裂。我自己的经历很典型。最开始我单独装 Claude Code跑通了后来想试试 Codex又单独装一遍结果两套 Node.js 版本要求不一样两套配置目录互相打架tmux 会话里切来切去经常搞混哪个窗口跑的是哪个工具。更别提模型接入Claude Code 走一套 API 配置Codex 走另一套想同时接本地模型和云端模型配置文件能写到你怀疑人生。openrig 这类项目的价值就在这儿它不发明新模型也不重写 AI 能力它做的是“机架”——把工具、运行时、会话、模型接入这几层标准化地装配起来。所以这篇内容适合谁看如果你只是偶尔用用网页版 AI 聊天那可以先收藏着但如果你已经或准备把 Claude Code、Codex 这类终端助手当成日常主力开发工具尤其是需要在 Windows、Ubuntu、VS Code 之间来回切换还想接本地模型或第三方 API那 openrig 这套思路值得你花时间吃透。下面我会从整体设计、核心细节、实操落地、问题排查四个层面把这件事讲清楚尽量让你看完就能自己搭一套。2. openrig 的整体设计与思路拆解2.1 为什么需要一层“机架”而不是各装各的先说一个很多人踩过的坑以为 Claude Code 和 Codex 是两个互不相干的工具各装各的最省事。短期看确实如此长期看是灾难。原因有三层。第一层是运行时冲突。Claude Code 和 Codex 都是基于 Node.js 生态的命令行工具但它们对 Node.js 版本的要求经常不一致。热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是活生生的例子——你照着某个教程去装一个还不存在的版本直接报错。如果你全局只装一个 Node.js两个工具可能有一个跑不起来如果你装多个版本又得靠 nvm 之类的版本管理器来回切切错了就是各种玄学报错。第二层是配置目录污染。这两个工具默认都会在用户主目录下建自己的配置文件夹里面存 API key、模型端点、会话历史、权限设置。你手动改来改去很容易出现“我明明改了配置但工具不生效”的情况因为可能改的是旧版本残留的目录或者被环境变量覆盖了。热词里codex is ignoring 1 unrecognized configuration setting. check for typos or d就是配置写错但工具只是警告不报错的典型排查起来很费劲。第三层是会话管理割裂。终端 AI 助手最爽的用法是长时间挂着会话边写代码边对话。tmux 就是干这个的。但如果你 Claude Code 开一个 tmux 窗口Codex 开另一个模型切换、上下文同步、日志查看全得手动来。openrig 的思路是把这些统一到一层“机架”上运行时用统一的 Node.js 版本策略配置用统一的目录结构和环境变量注入会话用 tmux 统一编排模型接入用统一的代理层。提示这里的“统一”不是强制所有工具用同一个配置而是提供一套标准化的装配规则让每个工具在规则内各取所需互不干扰。2.2 核心分层运行时层、工具层、会话层、模型层把 openrig 拆开看我习惯分成四层这个分层也决定了你后面实操时该先动哪一层。运行时层负责 Node.js 和包管理器。这是地基。我的建议是永远不要用系统自带的 Node.js而是用版本管理器nvm 或 fnm装一个 LTS 版本再为特殊工具准备一个独立版本。热词里node.js lts下载、安装node.js、node.js是干什么的说明很多人卡在这一步。Node.js 本质是让 JavaScript 能在浏览器外运行的运行时这些 AI 命令行工具都是用它写的所以它是前置依赖绕不开。工具层就是 Claude Code 和 Codex 本体以及它们的安装方式。这里有个关键选择全局安装还是项目内安装。全局安装方便但版本冲突风险高项目内安装隔离好但每个项目都要装一遍。openrig 这类机架通常倾向于用统一的安装脚本把工具装到一个受控的全局位置同时用包装脚本wrapper来注入环境变量。会话层是 tmux。tmux 是终端复用器简单说就是让你在一个终端窗口里开多个“窗格”和“窗口”并且断开连接后会话还在后台跑。对于 AI 编程助手这意味着你可以让 Claude Code 在一个窗格里持续工作自己在另一个窗格看日志或跑测试关掉终端再回来会话还在。热词里 tmux 反复出现说明这是刚需。模型层是最容易出问题的一层。Claude Code 默认接 Anthropic 的模型Codex 默认接 OpenAI 的模型但大家都想接第三方或本地模型。热词里claude code 调用lmstudio的本地模型、codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型全是这个诉求。openrig 的思路是提供一个本地代理层把不同工具的请求格式统一转换后转发到目标模型端点。热词里cc switch local proxy failed while handling codex endpoint /responses就是代理层出问题的典型报错后面我会专门讲怎么排查。2.3 方案选型背后的取舍逻辑为什么用 tmux 而不是 VS Code 内置终端因为 VS Code 终端是依附于编辑器进程的关掉编辑器会话就没了而且多窗口管理不如 tmux 灵活。tmux 是独立进程可以 SSH 上去接着用这对远程开发场景是刚需。热词里ubuntu配置claude code、ubuntu 安装claude code说明不少人在 Linux 服务器上跑tmux 几乎是标配。为什么强调 Node.js 版本管理而不是直接装最新版因为 AI 工具更新快今天要求 Node 18明天可能要求 Node 20后天某个依赖又只兼容 Node 22。用版本管理器可以随时切换不用卸载重装。热词里那个24.21.0 is not yet released的报错本质就是版本号写错了或者源里还没有用版本管理器就能清楚看到哪些版本真实可用。为什么模型接入要走本地代理而不是直接改工具配置因为每个工具的配置格式、认证方式、请求路径都不一样。直接改配置一旦工具升级配置格式变了你又得重来。本地代理层相当于一个适配器工具那边配置不变代理层负责翻译。代价是多了一个进程要维护但换来的是灵活性和可维护性。3. 核心细节解析与实操要点3.1 Node.js 运行时版本选择与安装避坑Node.js 这块我先给结论用 nvmLinux/macOS或 fnm跨平台Windows 也友好装一个 LTS 版本作为默认再按需装其他版本。不要用官网下载的安装包直接覆盖系统 Node也不要盲目追最新版。具体操作上Linux 和 macOS 下装 nvm 就是一行脚本的事装完nvm install --lts拿到当前 LTSnvm alias default lts/*设为默认。Windows 下我更推荐 fnm因为它对 PowerShell 支持好安装也简单。装完之后用node -v和npm -v验证。这里有个细节很多人忽略npm 的全局包安装路径。如果你切换了 Node 版本之前全局装的 Claude Code 或 Codex 可能就找不到了因为全局包是跟着 Node 版本走的。解决办法是要么每个版本都重装一遍工具要么用npm config set prefix把全局路径固定到一个与版本无关的目录。我一般选后者这样切版本不影响工具可用性。注意热词里error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错九成是版本号写错或镜像源没同步。先用nvm ls-remote看看真实可用的版本列表别照着来路不明的教程硬填版本号。3.2 Claude Code 与 Codex 的安装与共存Claude Code 和 Codex 的安装方式类似都是通过 npm 全局安装对应的包。安装本身不难难的是让它们共存且不互相干扰。我的做法是给每个工具建独立的配置目录通过环境变量指定。比如 Claude Code 用CLAUDE_CONFIG_DIR指向~/.config/openrig/claudeCodex 用对应的环境变量指向~/.config/openrig/codex。这样两个工具的配置、缓存、会话历史完全隔离升级或卸载一个不会影响另一个。安装顺序上先确保 Node.js 就绪再装 Claude Code验证能启动再装 Codex再验证。不要两个一起装出问题不好定位。验证的方式很简单跑一下工具的版本命令或帮助命令能正常输出就说明安装成功。热词里claude code安装、codex安装、codex安装 windows桌面版、codex安装 csdn说明安装教程满天飞但质量参差不齐。我的建议是优先看官方文档热词里claude code官方文档链接就是干这个的。第三方教程可以参考但版本号和命令要以官方为准因为工具更新太快半年前的教程可能已经失效。3.3 tmux 会话编排让 AI 助手常驻后台tmux 的用法不复杂但要用好需要一点设计。我的基本配置是一个 session 叫ai里面开三个 window。window 0 跑 Claude Codewindow 1 跑 Codexwindow 2 用来跑测试、看日志、执行 git 命令。每个 window 可以再分 pane比如 window 0 左边跑 Claude Code右边跑一个 tail 日志的命令。这样设计的好处是你 SSH 到服务器上tmux attach -t ai一下所有 AI 会话原封不动还在。关掉本地终端服务器上的会话继续跑。对于长时间让 AI 改代码、跑重构的场景这个体验是质的提升。tmux 配置上我建议改几个默认键位比如把前缀键从Ctrlb改成Ctrla因为Ctrlb在很多终端里和光标移动冲突。再开鼠标支持方便滚动和选择窗格。这些配置写在~/.tmux.conf里一次配置长期受益。提示tmux 会话里的环境变量是启动时继承的。如果你在会话启动后才改了 Node.js 版本或配置目录记得重启会话或手动 source 一下否则工具读到的还是旧环境。3.4 模型接入层本地代理与第三方 API 的配置要点模型接入是 openrig 这套体系里最灵活也最容易翻车的部分。核心思路是工具只认一个本地端点本地代理负责把请求转发到真正的模型服务。以 Claude Code 接本地模型为例你需要一个兼容 Anthropic 请求格式的代理把请求转成目标模型能懂的格式。Codex 接第三方模型同理需要一个兼容 OpenAI 请求格式的代理。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错说明代理在处理 Codex 的/responses端点时失败了可能原因是代理版本不支持这个端点或者请求格式转换有 bug。排查这类问题的顺序是先确认代理进程在跑再确认工具配置的端点地址和代理监听地址一致然后用 curl 手动打一下代理端点看返回什么。如果 curl 能通但工具不通那就是工具配置问题如果 curl 也不通那就是代理本身的问题。热词里codex无法加载组织设置、your organization has disabled claude subscription access for claude code这类报错多半是账号权限或订阅状态问题和代理无关要分开排查。4. 实操过程与核心环节实现4.1 从零搭建环境准备与依赖安装假设你是一台干净的 Ubuntu 机器我们从零走一遍。第一步装基础工具sudo apt update sudo apt install -y curl git tmux build-essential。这几样是后续所有操作的前提curl 用来下载git 用来拉代码tmux 用来管会话build-essential 用来编译某些 npm 原生依赖。第二步装 Node.js 版本管理器。以 nvm 为例用官方脚本安装装完 source 一下 shell 配置然后nvm install --lts。装完验证node -v应该输出一个 LTS 版本号。如果输出的是系统自带的老版本说明 nvm 没生效检查 shell 配置里有没有正确加载 nvm。第三步配置 npm 全局路径。npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里。这一步是为了让全局安装的工具不随 Node 版本切换而丢失。做完之后npm config get prefix确认一下。第四步装 Claude Code 和 Codex。用 npm 全局安装对应的包装完分别跑版本命令验证。如果某个工具报找不到命令检查 PATH 和全局路径配置。4.2 配置隔离让两个工具各用各的配置目录环境就绪后建配置目录结构。我一般这样组织mkdir -p ~/.config/openrig/claude mkdir -p ~/.config/openrig/codex mkdir -p ~/.config/openrig/logs然后在 shell 配置里加环境变量把两个工具的配置目录分别指过去。具体变量名以各工具官方文档为准因为工具版本不同变量名可能有差异。加完之后重新加载 shell 配置再启动工具确认配置写到了新目录而不是默认目录。这一步的验证方法是启动工具后随便改一个配置项然后去对应目录看文件有没有更新。如果更新在默认目录而不是你指定的目录说明环境变量没生效检查变量名拼写和加载顺序。注意环境变量的加载顺序很重要。如果你在.bashrc和.profile里都写了可能互相覆盖。建议只在一个地方写并且确保非交互式 shell 也能加载到否则 tmux 里启动的工具可能读不到。4.3 tmux 编排一键拉起整套 AI 工作台配置隔离做完就可以用 tmux 把整套工作台串起来。我写了一个启动脚本逻辑是检查是否已有ai会话有就 attach没有就新建并配置好窗口和窗格。脚本核心命令大概是tmux new-session -d -s ai -n claude建会话和第一个窗口然后tmux new-window -t ai -n codex建第二个窗口tmux new-window -t ai -n shell建第三个。再往窗口里发命令比如tmux send-keys -t ai:claude claude Enter。这样每次开工跑一下脚本三个窗口就绪Claude Code 和 Codex 各自在自己的窗口里跑互不干扰。需要看日志或跑命令就切到 shell 窗口。关掉终端再回来tmux attach -t ai一切照旧。脚本里我还会加一些健壮性检查比如 Node.js 版本对不对、工具在不在 PATH 里、配置目录存不存在。任何一项不满足就打印提示并退出避免带着错误环境启动。4.4 模型接入实操以接本地模型为例接本地模型这块假设你本地已经跑了一个兼容 OpenAI 或 Anthropic 格式的模型服务。第一步确认模型服务的地址和端口比如http://127.0.0.1:1234。第二步启动本地代理把代理的监听地址配成工具要访问的地址把上游地址配成模型服务地址。代理启动后用 curl 验证curl http://127.0.0.1:代理端口/v1/models看能不能列出模型。能列出说明代理到模型服务这段通了。然后配置工具把 API base 指向代理地址API key 随便填一个本地代理通常不校验模型名填代理支持的模型名。启动工具发一条简单消息看能不能正常返回。如果报错看代理日志日志里会显示请求转发到了哪里、返回了什么。热词里claude code 调用lmstudio的本地模型这类场景关键就是代理要正确转换请求格式因为 LM Studio 的接口格式和 Anthropic 的不完全一样。提示本地模型服务通常对并发和上下文长度有限制。如果你在 tmux 里同时跑 Claude Code 和 Codex 都接同一个本地模型可能会互相抢资源。建议错开使用或者给每个工具配不同的模型实例。5. 常见问题与排查技巧实录5.1 安装类问题速查安装阶段的问题最集中我整理了一张速查表覆盖热词里出现的高频报错。报错关键词可能原因排查动作node.js v24.21.0 is not yet released版本号写错或源未同步用 nvm ls-remote 查真实可用版本安装后命令找不到全局路径未加入 PATH检查 npm prefix 和 PATH 配置工具启动即退出Node 版本不兼容切换 Node 版本重试权限拒绝全局目录权限问题检查目录属主和权限位这张表里的每一条我都实际遇到过。尤其是版本号那条很多人照着博客里的命令直接复制博客写的时候那个版本存在等你看到的时候可能已经被撤了或者还没发布。养成先查可用版本再安装的习惯能省很多时间。5.2 配置类问题排查思路配置类问题的典型表现是“改了不生效”或“工具忽略了某个设置”。热词里codex is ignoring 1 unrecognized configuration setting就是工具读到了配置但不认识只是警告不报错。这种情况要去看工具的配置文档确认字段名和格式。排查配置问题的通用思路是先确认工具读的是哪个配置文件再确认文件内容格式正确最后确认没有环境变量覆盖。很多工具支持--verbose或--debug之类的参数启动时加上能看到它实际加载了哪些配置。如果工具没有这个参数就去看它的日志文件通常在配置目录下的 logs 子目录里。还有一个常见坑是配置文件的格式。有的工具用 JSON有的用 YAML有的用 TOML。JSON 里多一个逗号、YAML 里缩进错一格都可能导致整个配置被忽略。改完配置用工具自带的校验命令或在线校验器过一遍能避免大部分低级错误。5.3 代理与模型接入问题实录代理层的问题最隐蔽因为涉及工具、代理、模型服务三个环节。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错我的排查顺序是这样的。先看代理进程是否存活ps aux | grep 代理名确认。再看代理监听的端口是否和工具配置的一致ss -tlnp | grep 端口确认。然后用 curl 直接打代理端点看返回什么。如果 curl 返回 404说明代理没实现这个端点需要升级代理或换一个支持该端点的代理。如果 curl 返回 500看代理日志里的堆栈通常是请求格式转换失败。工具侧的问题重点看 API base 配置和认证配置。有的工具要求 API base 带/v1有的不带配错了就是 404。认证方面本地代理通常不校验 key但工具可能强制要求填随便填一个非空字符串即可。如果工具报认证失败先确认代理是否真的不校验再确认 key 有没有被 shell 转义搞坏。5.4 会话与 tmux 问题排查tmux 相关的问题主要是会话丢失、窗格错乱、环境变量不对。会话丢失通常是机器重启或 tmux 进程被杀这个没办法只能重新拉起。窗格错乱多半是误触了快捷键tmux kill-session重来最快。环境变量不对是启动顺序问题前面提过重启会话或手动 source 即可。还有一个容易被忽略的点是 tmux 里的终端类型。有的 AI 工具会根据终端类型决定是否启用彩色输出或交互模式。如果 tmux 里工具行为异常检查echo $TERM正常应该是screen或tmux-256color。如果是dumb说明终端类型没设对在 tmux 配置里加上set -g default-terminal tmux-256color能解决。6. 我踩过的坑和几条实在建议先说一个最坑的不要在生产环境的系统 Node 上直接装这些工具。我有一次在一台服务器上图省事直接用系统 Node 装了 Claude Code结果后来系统更新把 Node 升级了工具直接跑不起来排查了半天才发现是版本问题。从那以后我所有机器都用版本管理器系统 Node 只用来跑系统脚本绝不碰。第二个坑是配置文件乱放。早期我没做配置隔离两个工具的配置混在一个目录里改 A 的时候不小心动了 B 的字段结果 B 启动就报错。后来严格按工具分目录每个工具的环境变量在启动脚本里显式注入再没出过这类问题。第三个坑是代理层版本不匹配。工具升级后请求格式变了代理还是老版本就会出现local proxy failed这类报错。我的做法是代理和工具一起升级升级前先看两者的兼容性说明。如果代理项目更新不活跃就换一个活跃的替代品别硬扛。最后给几条实在建议。第一所有配置和脚本都进 git换机器时 clone 下来就能用比手动配快十倍。第二tmux 会话名和窗口名起得有意义别用默认的 0、1、2时间长了根本记不住哪个是哪个。第三模型接入先跑通最简单的云端模型再折腾本地模型和第三方 API一步步来别一上来就搞最复杂的组合。第四遇到报错先看日志工具的日志、代理的日志、模型服务的日志三个都看大部分问题日志里写得清清楚楚比在网上搜半天快得多。这套 openrig 思路的核心不是某个具体工具而是“分层装配、配置隔离、会话常驻、接入统一”这十六个字。你把这四件事做到位不管以后换什么 AI 编程助手都能快速接进来不用每次都从零折腾环境。