openrig环境编排：Claude Code与Codex共存配置与本地模型接入指南

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟“rig”这个词在硬件圈里太常见了。但翻了一圈社区讨论和实际代码之后才明白它其实是围绕 Claude Code、Codex 这类终端 AI 编程助手搭建的一套本地运行环境编排方案。说白了openrig 解决的是一个很具体的问题当你同时用着 Claude Code 和 Codex 两个命令行工具又想让它们共享同一套 Node.js 运行时、同一套终端会话管理、同一套本地模型接入配置的时候怎么把这件事做得干净、可复现、不互相打架。这个需求不是凭空冒出来的。我自己最开始是单独装 Claude Code用了一阵子觉得某些场景下 Codex 的补全风格更顺手于是又装了 Codex。结果两个工具各自拉了一套 Node.js 依赖终端里 tmux 会话命名冲突环境变量互相覆盖最头疼的是本地模型接入的代理配置两边格式不一样改完这边那边就挂。openrig 的思路就是把这些东西统一到一个 rig 里面来管理让 Claude Code 和 Codex 在同一个终端环境下和平共处。适合谁来参考这篇内容如果你已经在用或者打算用 Claude Code、Codex 这类终端 AI 编程工具手头有 Node.js 环境平时在 Ubuntu 或者 Windows 上做开发并且对 tmux 会话管理不陌生那这篇东西就是写给你的。如果你只是听说过这些工具还没上手也没关系我会把基础的环境准备和安装步骤都铺开讲保证你能跟着走下来。注意openrig 本身不是一个官方项目它更像是社区里一群人踩坑之后总结出来的一套环境组织方式。所以下面讲的内容里有一部分是基于常见实践的合理补全不是某个官方文档的逐字翻译。2. 为什么需要 openrig 这样的环境编排2.1 多工具共存时的真实痛点先说说不用 openrig 的时候同时跑 Claude Code 和 Codex 会遇到什么。最典型的问题是 Node.js 版本冲突。Claude Code 对 Node.js 的版本要求比较宽松18 以上基本都能跑但 Codex 在某些版本上会报出类似“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”这样的错误说明它对 Node.js 的版本探测逻辑跟 Claude Code 不一样。如果你系统里只装了一个全局 Node.js两个工具可能有一个能跑一个报错。第二个问题是终端会话管理。Claude Code 在执行终端命令的时候底层往往会借助 tmux 来维持一个持久的 shell 会话这样它才能在多轮对话里记住当前工作目录、环境变量这些上下文。Codex 也有类似机制但两个工具如果各自开各自的 tmux 会话你在排查问题的时候就会看到一堆名字相近的 session分不清哪个是哪个。openrig 的做法是统一 tmux 会话的命名规范和生命周期管理让两个工具共用一套会话策略。第三个问题是本地模型接入。现在很多人不想完全依赖云端 API而是想在本地跑模型然后让 Claude Code 或者 Codex 去调用。这就涉及到代理配置。社区里有人遇到过“cc switch local proxy failed while handling codex endpoint /responses”这种报错本质上是代理层在转发请求的时候对 Codex 的 /responses 端点和 Claude Code 的端点处理方式不一致导致的。openrig 把代理配置也纳入统一管理避免两边各配各的。2.2 openrig 的核心设计思路openrig 的设计思路可以用一句话概括把 Claude Code 和 Codex 当作同一个 rig 上的两个工具头底下的运行时、会话层、代理层全部共享。具体来说分三层。最底层是 Node.js 运行时层。openrig 不要求你系统全局只装一个 Node.js而是建议用版本管理工具比如 nvm 或者 fnm准备一个专门给 AI 编程工具用的 Node.js 版本。这样做的好处是即使你系统里其他项目需要不同版本的 Node.js也不会影响到 Claude Code 和 Codex 的运行。我实测下来Node.js 20 LTS 是目前最稳的选择Claude Code 和 Codex 在这个版本上都没出现过兼容性问题。中间层是终端会话层。openrig 统一用 tmux 来管理会话给 Claude Code 和 Codex 分别分配固定的 session 名前缀比如 claude- 和 codex- 开头。这样你在 tmux ls 的时候一眼就能看出哪个会话属于哪个工具。同时 openrig 还定义了一套会话清理策略避免长时间运行之后堆积一堆死会话。最上层是代理与模型接入层。如果你用本地模型openrig 建议用一个统一的代理进程来转发请求而不是让 Claude Code 和 Codex 各自直连本地模型服务。这样做的好处是代理层可以做统一的日志记录、请求改写和错误处理。社区里有人用 cc switch 来切换不同的模型后端比如 DeepSeek、Qwen、GLM 这些openrig 的思路是把这类切换逻辑也纳入代理层统一管理。2.3 跟单独安装相比openrig 省了什么可能你会觉得不就是装两个工具吗至于搞这么复杂我一开始也这么想但实际踩过坑之后发现单独安装的问题不在于装的那一下而在于后续维护。单独装的时候Claude Code 和 Codex 各自管各自的依赖升级的时候可能一个升了另一个没升然后两个工具的行为就不一致了。openrig 把升级也统一了你只需要在一个地方更新 Node.js 版本和工具版本两个工具同时生效。另一个省掉的是排查问题的时间。单独装的时候出了问题你得先判断是 Claude Code 的问题还是 Codex 的问题还是 Node.js 的问题还是 tmux 的问题。openrig 因为分层清晰排查的时候可以逐层排除先看 Node.js 版本对不对再看 tmux 会话正不正常最后看代理层日志。这个排查路径比东一榔头西一棒子要高效得多。3. 环境准备Node.js 与 tmux 的安装配置3.1 Node.js 版本选择与安装Node.js 是 Claude Code 和 Codex 的运行基础这一步没搞好的话后面全是坑。先说版本选择。Node.js 的发布节奏是偶数版本号进入 LTS长期支持奇数版本号是过渡版本。目前 20.x 是活跃 LTS22.x 也已经是 LTS 了。我建议用 20.x因为社区里大量 Claude Code 和 Codex 的配置示例都是基于 20.x 写的遇到问题更容易找到参考。在 Ubuntu 上安装 Node.js 20最省事的方式是用 NodeSource 的仓库。先更新包列表然后添加 NodeSource 的源再安装。具体命令如下sudo apt update sudo apt install -y ca-certificates curl gnupg sudo mkdir -p /etc/apt/keyrings curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg echo deb [signed-by/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main | sudo tee /etc/apt/sources.list.d/nodesource.list sudo apt update sudo apt install -y nodejs装完之后用 node -v 确认版本。如果显示 v20.x.x 就对了。这里有个细节要注意如果你之前用 apt 装过 Ubuntu 自带的 Node.js版本可能比较老需要先卸载掉再走上面的流程否则会出现两个 Node.js 打架的情况。Windows 上的话直接去 Node.js 官网下载 LTS 版本的安装包就行。安装的时候记得勾选“Add to PATH”这样在 PowerShell 或者 CMD 里才能直接调用 node 和 npm。如果你用 winget也可以直接 winget install OpenJS.NodeJS.LTS 来装。提示不管你用哪个系统装完 Node.js 之后都建议跑一下 npm -v 确认 npm 也能正常工作。有时候 Node.js 装好了但 npm 没跟着装上这种情况虽然少见但确实遇到过。3.2 tmux 的安装与基础配置tmux 在 openrig 里的角色是终端会话的容器。Claude Code 和 Codex 在执行终端命令的时候需要一个持久的 shell 环境来保持上下文tmux 就是干这个的。Ubuntu 上装 tmux 很简单sudo apt install -y tmuxWindows 上稍微麻烦一点因为 tmux 原生不支持 Windows。常见的做法是在 WSL2 里面装 tmux然后 Claude Code 和 Codex 也在 WSL2 里跑。如果你坚持要在 Windows 原生环境跑可以考虑用 MSYS2 或者 Cygwin 提供的 tmux 替代方案但体验不如 WSL2 顺畅。我自己的做法是 Windows 上开 WSL2Ubuntu 环境里装 tmux然后 VS Code 通过 Remote-WSL 连进去这样 Claude Code 和 Codex 都能在 WSL2 里正常工作。tmux 装好之后建议做一点基础配置让会话管理更顺手。在 ~/.tmux.conf 里加上这几行set -g base-index 1 setw -g pane-base-index 1 set -g renumber-windows on set -g history-limit 10000 set -g mouse onbase-index 设为 1 是为了让窗口编号从 1 开始符合大多数人的直觉。history-limit 调大是为了让 Claude Code 和 Codex 输出的长日志不会被截断。mouse on 是开启鼠标支持方便滚动查看历史输出。这些配置不是必须的但加上之后日常使用会舒服很多。3.3 验证环境是否就绪装完 Node.js 和 tmux 之后跑几个命令确认环境没问题。先看 Node.js 版本node -v npm -v再看 tmux 能不能正常创建和销毁会话tmux new-session -d -s test-session tmux ls tmux kill-session -t test-session如果 tmux ls 能看到 test-sessionkill 之后再看就没了说明 tmux 工作正常。这两步都过了基础环境就算准备好了。4. Claude Code 与 Codex 的安装与共存配置4.1 Claude Code 的安装方式Claude Code 的安装方式取决于你用哪个平台。在 Ubuntu 或者 WSL2 里最直接的方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code装完之后在终端里输入 claude 应该就能启动。第一次启动会引导你做认证按照提示走就行。如果你在 Windows 原生环境除了 npm 安装之外还可以用 Claude Code 的桌面版不过桌面版和命令行版在功能上有些差异命令行版对终端命令的执行支持更完整。VS Code 用户还可以装 Claude Code for VS Code 扩展这样在编辑器里就能直接调用。不过扩展本质上还是调用底层的命令行工具所以 Node.js 环境还是得先配好。我自己的习惯是在 VS Code 的集成终端里直接用命令行版因为这样对 tmux 会话的控制更直接。安装过程中可能遇到的问题如果你的 npm 全局安装目录没有加到 PATH 里装完之后输入 claude 会提示找不到命令。解决办法是确认 npm 的全局 bin 目录在 PATH 里。用 npm config get prefix 可以看到 npm 的全局前缀然后确认那个前缀下的 bin 目录在 PATH 里。4.2 Codex 的安装方式Codex 的安装跟 Claude Code 类似也是通过 npm 全局安装。不过 Codex 的包名和安装命令跟 Claude Code 不一样具体命令根据你用的版本会有所变化。安装之前建议先确认 Node.js 版本符合要求前面提到的“error installing 24.21.0”那个报错就是因为 Node.js 版本探测出了问题。Codex 装完之后同样需要认证。社区里有人遇到过“codex登录不上”或者“codex无法加载组织设置”这类问题大多数情况下是认证配置的问题。如果你用的是组织账号需要确认组织管理员没有禁用相关权限。如果遇到“your organization has disabled claude subscription access for claude code”这种提示那是账号权限层面的问题跟本地环境无关需要找管理员处理。Codex 还有一个常见问题是配置文件里的未知设置项。如果你看到“codex is ignoring 1 unrecognized configuration setting. check for typos or d”这样的警告说明你的配置文件里有一项 Codex 不认识的设置。这个警告本身不影响使用但最好还是把配置清理一下避免以后出问题。4.3 让两个工具共用一套 Node.js 环境openrig 的核心目标之一就是让 Claude Code 和 Codex 共用同一套 Node.js 环境。实现方式很简单两个工具都用 npm 全局安装而 npm 全局安装用的是同一个 Node.js 版本。只要你没有在系统里装多个 Node.js 版本并且来回切换两个工具自然就共用了。但这里有个坑如果你用 nvm 管理 Node.js 版本切换版本的时候全局安装的包不会跟着走。也就是说你在 Node.js 20 下装的 Claude Code切到 Node.js 18 之后就找不到了。openrig 的建议是给 AI 编程工具专门固定一个 Node.js 版本不要跟其他项目混用。具体做法是在 shell 的配置文件里针对特定目录自动切换 Node.js 版本或者干脆就用系统级的 Node.js 20不用 nvm。我自己的做法是在 Ubuntu 上用系统级 Node.js 20不用 nvm。这样 Claude Code 和 Codex 都装在同一个全局目录下升级 Node.js 的时候两个工具一起受影响行为一致。如果你确实需要用 nvm 管理多个版本那就在每次切换版本之后重新全局安装一遍 Claude Code 和 Codex虽然麻烦一点但能保证一致性。4.4 tmux 会话的命名与隔离Claude Code 和 Codex 在运行过程中都会创建 tmux 会话。如果不加管理你会看到一堆名字随机的会话时间长了根本分不清。openrig 的做法是给两个工具的会话加上固定前缀。Claude Code 的 tmux 会话前缀设为 claude-Codex 的设为 codex-。这样在 tmux ls 的时候输出大概是这样的claude-main: 1 windows (created Mon Jan 1 10:00:00 2024) codex-main: 1 windows (created Mon Jan 1 10:00:01 2024)一眼就能看出哪个是哪个。设置前缀的方式取决于工具本身是否支持自定义会话名。如果工具不支持可以在启动工具之前手动创建 tmux 会话然后让工具在那个会话里运行。比如tmux new-session -d -s claude-main tmux send-keys -t claude-main claude Enter这样 Claude Code 就在 claude-main 这个会话里跑起来了。Codex 同理。这样做的好处是会话名完全由你控制不会出现随机名字。注意手动创建 tmux 会话然后 send-keys 的方式在工具需要交互式输入的时候可能会有点别扭。如果你发现工具在 tmux 会话里响应不正常可以试试直接在 tmux 会话里手动输入命令而不是用 send-keys。5. 本地模型接入与代理配置5.1 本地模型接入的基本原理Claude Code 和 Codex 默认都是调用云端 API 的但很多人出于成本、隐私或者网络稳定性的考虑想用本地模型。本地模型接入的基本原理是在本地跑一个模型服务比如 LM Studio、Ollama 或者自己用推理框架搭的服务然后让 Claude Code 和 Codex 把请求发到这个本地服务而不是发到云端。这里的关键是接口兼容性。Claude Code 和 Codex 各自期望的 API 格式可能不一样而本地模型服务提供的 API 格式又是另一套。所以通常需要一个代理层来做格式转换。社区里有人用 cc switch 来做这件事它可以在不同的模型后端之间切换并且处理格式转换。代理层的配置是 openrig 里最容易出问题的部分。常见的报错包括“cc switch local proxy failed while handling codex endpoint /responses”这说明代理层在处理 Codex 的 /responses 端点时出了问题。排查的时候先确认代理层是否在运行再看代理层的日志里有没有更详细的错误信息。5.2 代理配置的实操步骤假设你用 LM Studio 在本地跑了一个模型LM Studio 默认的 API 地址是 http://localhost:1234/v1。现在要让 Claude Code 和 Codex 都能通过代理层调用这个本地模型。第一步确认 LM Studio 的本地服务已经启动并且模型已经加载。在浏览器或者用 curl 访问 http://localhost:1234/v1/models 应该能看到模型列表。第二步启动代理层。代理层的具体启动方式取决于你用哪个工具。以 cc switch 为例它通常需要你指定后端模型的地址和 API 格式。配置好之后启动代理代理会监听一个本地端口比如 8080。第三步配置 Claude Code 和 Codex 使用代理。Claude Code 通常通过环境变量来指定 API 地址比如设置 ANTHROPIC_BASE_URL 或者类似的变量指向代理地址。Codex 也有类似的配置项。具体变量名和配置方式需要参考各自工具的文档。第四步测试。在 Claude Code 里发一个简单的请求看代理层的日志里有没有收到请求以及请求是否成功转发到了 LM Studio。如果代理层日志显示请求收到了但转发失败检查 LM Studio 的地址和端口对不对。如果代理层根本没收到请求检查 Claude Code 的环境变量配置对不对。5.3 常见代理报错与排查代理配置这块踩坑最多我整理了一个常见报错速查表报错信息可能原因排查方向cc switch local proxy failed while handling codex endpoint /responses代理层对 Codex 的 /responses 端点处理逻辑有误检查代理层版本确认是否支持 Codex 的 API 格式the gpt-5.6-sol model is not supported when using codex with a...模型名称不被支持检查模型名称拼写确认代理层是否做了模型名映射codex is ignoring 1 unrecognized configuration setting配置文件里有未知设置项检查 Codex 配置文件移除不认识的设置项codex无法加载组织设置账号权限或网络问题确认账号权限检查网络连接codex登录不上认证配置问题重新走认证流程检查认证文件是否完整排查代理问题的通用思路是先看代理层日志再看工具端日志最后看模型服务端日志。三层日志对照着看基本能定位到问题出在哪一层。如果代理层日志里连请求都没收到那问题在工具端的配置。如果代理层收到了请求但转发失败问题在代理层到模型服务这一段。如果模型服务收到了请求但返回错误问题在模型本身。6. 实操心得与避坑指南6.1 安装顺序很重要我踩过的一个坑是安装顺序不对导致环境混乱。正确的顺序应该是先装 Node.js再装 tmux然后装 Claude Code 和 Codex最后配代理。如果先装了 Claude Code 再装 Node.js可能会出现 Claude Code 找不到 Node.js 的情况。虽然理论上 npm 全局安装的包会记录 Node.js 路径但实际用下来先装 Node.js 再装工具是最稳的。另一个顺序问题是如果你要用本地模型先把本地模型服务跑起来再配代理最后配工具。这样每一步都能单独验证出了问题容易定位。如果一股脑全配完再测试出了问题得从头排查效率很低。6.2 版本锁定与升级策略Claude Code 和 Codex 都在快速迭代版本更新很频繁。我的建议是不要盲目追新而是锁定一个已知稳定的版本等社区反馈没问题了再升级。具体做法是在 npm 安装的时候指定版本号比如 npm install -g anthropic-ai/claude-code1.2.3 这样。虽然这样装的时候麻烦一点但能避免自动升级带来的意外问题。Node.js 版本也一样锁定在 20 LTS 就不要随便动。除非 Claude Code 或者 Codex 明确要求更高的 Node.js 版本否则没必要升级。升级 Node.js 版本的时候记得把 Claude Code 和 Codex 都重新安装一遍确保它们链接到新的 Node.js 运行时。6.3 tmux 会话清理长时间运行之后tmux 里会堆积很多死会话。这些死会话虽然不占太多资源但会让 tmux ls 的输出很乱。建议定期清理tmux ls | grep -E ^(claude-|codex-) | cut -d: -f1 | xargs -I {} tmux kill-session -t {}这条命令会杀掉所有以 claude- 或 codex- 开头的 tmux 会话。注意不要在工具正在运行的时候执行否则会中断工具的工作。最好在一天的工作结束之后清理一次。6.4 配置文件备份Claude Code 和 Codex 的配置文件、认证文件、代理配置这些建议定期备份。这些文件通常放在用户主目录下的隐藏目录里比如 ~/.claude/ 和 ~/.codex/ 这样的路径。备份的时候直接打包整个目录就行。这样即使环境出了问题需要重装配置也能快速恢复。我自己的做法是用 git 管理这些配置文件把 ~/.claude/ 和 ~/.codex/ 里的关键配置文件纳入版本控制。这样不仅能备份还能看到配置的变更历史排查问题的时候很有用。不过要注意认证文件里可能包含敏感信息不要提交到公开仓库。6.5 网络问题的排查思路Claude Code 和 Codex 都需要网络连接如果你用的是云端 API网络问题会直接导致工具不可用。常见的网络问题包括连接超时、DNS 解析失败、SSL 证书错误等。排查的时候先用 curl 测试一下 API 端点是否可达然后再看工具端的报错。如果你用的是本地模型网络问题通常出在 localhost 的端口占用或者防火墙规则上。确认本地模型服务监听的端口没有被其他程序占用防火墙没有阻止 localhost 的流量。Ubuntu 上可以用 ss -tlnp 查看端口监听情况Windows 上可以用 netstat -ano。7. 后续可以怎么扩展openrig 这套环境搭好之后其实还有很多可以扩展的方向。比如你可以把常用的 Claude Code 和 Codex 配置写成脚本一键切换不同的模型后端。社区里有人做了 cc switch 这样的工具就是干这个的。你也可以自己写一个简单的 shell 脚本根据参数切换环境变量和代理配置。另一个扩展方向是把 openrig 跟 VS Code 更深度地集成。VS Code 的 Remote-WSL 或者 Remote-SSH 功能可以让你在本地编辑器里直接操作远程的 Claude Code 和 Codex 环境。这样你既享受了本地编辑器的便利又利用了远程服务器的计算资源。还有一个方向是日志和监控。Claude Code 和 Codex 运行过程中会产生大量日志这些日志对于排查问题和优化使用体验很有价值。你可以把代理层的日志、工具端的日志、tmux 会话的输出统一收集到一个地方方便检索和分析。简单的做法是用 tee 命令把输出同时写到文件和终端复杂一点的做法是搭一个日志收集系统。我个人在实际操作中的体会是openrig 这套东西的价值不在于它有多复杂而在于它把原本散落各处的配置和流程收拢到了一起。你不需要每次都从头回忆“上次那个代理是怎么配的”而是有一套固定的流程可以照着走。踩过几次坑之后我把常用的命令和配置都写成了一个 setup 脚本新环境上跑一遍脚本就能把 Claude Code 和 Codex 都配好省了很多重复劳动。如果你也经常在不同机器上切换建议你也这么做。