1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟“rig”在英文里常指设备支架、装置。但结合 Claude Code、Codex、Node.js、tmux 这几个关键词一起出现基本可以判断这是一个围绕 AI 编程助手运行环境搭建与管理的工具或方案集合。简单说openrig 要解决的核心痛点是当你同时使用 Claude Code、Codex 这类终端 AI 编程助手时如何在一个干净、可控、可复现的环境里把它们跑起来并且让它们之间能顺畅切换、共享上下文、稳定调用本地或远程模型。我自己在过去大半年里先后在 Ubuntu 和 Windows 上折腾过 Claude Code 和 Codex 的安装配置踩过的坑包括 Node.js 版本不对导致安装失败、tmux 会话里环境变量丢失、切换模型时代理配置冲突、Codex 报“组织设置无法加载”等等。这些问题单独看都不算大但堆在一起就会让人抓狂。openrig 这类方案的价值就在于把这些零散的环境准备、依赖管理、会话保持、模型切换逻辑打包成一套可复用的流程。适合读这篇内容的人有三类第一类是刚接触 Claude Code 或 Codex连 Node.js 该装哪个版本都不确定的新手第二类是在 Ubuntu 服务器上跑 AI 助手需要 tmux 保持长会话的运维型用户第三类是已经在用多个模型服务想通过统一入口管理 Claude Code、Codex 以及第三方 API 的中高级玩家。不管你属于哪一类下面这些实操细节都能直接拿去用。2. 环境底座Node.js 与 tmux 的正确打开方式2.1 Node.js 版本选择与安装避坑Claude Code 和 Codex 的 CLI 工具绝大多数是基于 Node.js 生态分发的所以 Node.js 是绕不开的第一道坎。网上搜“node.js安装”“node.js下载”会出来一堆结果但真正需要注意的是版本。我实测下来Claude Code 对 Node.js 18 和 20 的支持最稳Codex 的 CLI 也基本在这个区间。Node.js 22 虽然更新但部分原生模块编译时会出问题尤其是你在 Ubuntu 上直接跑npm install -g的时候。有一个热搜词是“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”这其实是一个典型的版本号误判问题。很多教程里写的版本号是示例实际安装时如果照抄npm 会去 registry 里找不存在的版本自然报错。正确的做法是去 Node.js 官网下载 LTS 版本或者用 nvm 管理多版本。在 Ubuntu 上安装 Node.js 20 的推荐流程# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v npm -v用 nvm 的好处是当你需要切换不同项目时可以随时nvm use 18或nvm use 20不会污染系统全局环境。Windows 用户可以直接去 Node.js 官网下载 LTS 的 msi 安装包安装时勾选“Add to PATH”省去手动配置环境变量的麻烦。注意不要用apt install nodejs直接装 Ubuntu 仓库里的版本那个版本往往太旧Claude Code 和 Codex 都可能跑不起来。也不要用sudo npm install -g混用系统 Node 和 nvm Node权限问题会让你怀疑人生。2.2 tmux 会话保持与 AI 助手长任务tmux 在这个场景里的作用经常被低估。Claude Code 和 Codex 在执行复杂任务时可能会跑几分钟甚至更久如果你是通过 SSH 连到远程服务器网络一断任务就没了。tmux 能创建一个持久会话断开 SSH 后进程继续跑重新连上后tmux attach就能看到完整输出。安装 tmux 很简单sudo apt update sudo apt install tmux -y创建一个专门跑 AI 助手的会话tmux new -s airig在这个会话里再启动 Claude Code 或 Codex。我习惯把会话命名为airig对应 openrig 的概念方便记忆。如果你同时跑多个模型服务可以开多个窗口# 在 tmux 会话内 Ctrlb c # 新建窗口 Ctrlb n # 切换到下一个窗口 Ctrlb p # 切换到上一个窗口 Ctrlb d # 分离会话进程继续后台运行有一个细节很多人会忽略tmux 会话里的环境变量可能和你登录 shell 的不一致。比如你在.bashrc里配置了 API Key但 tmux 启动时如果没有加载.bashrcClaude Code 就会报认证失败。解决办法是在 tmux 里手动source ~/.bashrc或者把关键环境变量写进.tmux.conf的set-environment里。3. Claude Code 与 Codex 的安装配置实战3.1 Claude Code 安装与 VS Code 集成Claude Code 的安装方式随着版本迭代有过变化目前比较稳的方式是通过 npm 全局安装。热搜词里“claude code安装”“claude code下载安装”“claude code windows”都指向同一个需求怎么把它装到本地并跑起来。在 Node.js 20 环境下npm install -g anthropic-ai/claude-code安装完成后直接在终端输入claude就能进入交互界面。第一次运行会引导你登录或配置 API Key。如果你用的是官方订阅按提示走 OAuth 流程即可如果你是通过第三方 API 接入需要设置环境变量export ANTHROPIC_API_KEY你的key export ANTHROPIC_BASE_URL你的接口地址VS Code 集成是另一个高频需求“vscode配置claude code”“claude code for vs code”“vscode接入claude code”这些搜索词说明很多人希望在编辑器里直接用。目前 Claude Code 有官方 VS Code 扩展装完后在 VS Code 的设置里填入 API Key 或登录账号就能在编辑器内调用。实测下来VS Code 扩展的响应速度比终端版稍慢但胜在能直接读取当前打开的文件和选中代码做代码解释和重构时非常方便。实操心得如果你在 VS Code 里遇到“your organization has disabled claude subscription access for claude code”这类提示通常是因为账号权限或订阅类型不匹配。先确认你的账号是否支持 Claude Code 功能再检查是否在正确的组织下。切换账号后记得重启 VS Code否则缓存会导致旧状态残留。3.2 Codex 安装与常见报错处理Codex 的安装同样依赖 Node.js但它的配置项比 Claude Code 更细碎出问题的概率也更高。热搜词里“codex安装教程”“codex安装包”“codex安装 windows桌面版”“codex登录不上”“codex无法加载组织设置”几乎覆盖了新手会遇到的所有坑。基础安装npm install -g openai/codex安装后运行codex进入交互。Codex 的登录方式有几种最常见的是通过浏览器 OAuth 或 API Key。如果你在公司网络环境下可能会遇到登录回调失败这时候可以尝试手动复制回调 URL 里的 code 参数粘贴到终端完成认证。“codex无法加载组织设置”这个报错我遇到过两次。第一次是因为账号同时属于多个组织Codex 默认去拉第一个组织的配置但那个组织没有开通 Codex 权限。解决办法是在 Codex 配置里显式指定组织 IDcodex config set organization 你的组织ID第二次是因为本地缓存的 token 过期但 Codex 没有正确提示重新登录。删掉~/.codex目录下的缓存文件重新登录就好了。还有一个热搜词是“codex is ignoring 1 unrecognized configuration setting. check for typos or d”这是配置文件里有 Codex 不认识的字段。Codex 的配置文件通常是~/.codex/config.toml或项目根目录下的.codex.toml。遇到这个警告时逐行检查配置项名称尤其是从网上抄来的配置不同版本的 Codex 支持的字段不一样。3.3 模型接入从本地 LM Studio 到第三方 API“claude code 调用lmstudio的本地模型”和“codex接入deepseek”这两个搜索词代表了两种典型需求一是完全本地化运行不依赖外部网络二是用第三方 API 替代官方服务降低成本或获取特定模型能力。Claude Code 调用 LM Studio 本地模型的配置思路是LM Studio 启动一个兼容 OpenAI 格式的本地服务然后把 Claude Code 的 API 地址指向这个本地端口。LM Studio 默认端口是 1234启动服务后export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio然后在 Claude Code 里选择模型时填入 LM Studio 里加载的模型名称。实测下来本地模型在代码补全和简单重构上够用但复杂推理任务还是得靠更大的模型。Codex 接入 DeepSeek 或其他第三方 API 的逻辑类似但 Codex 的配置更依赖config.toml[model] provider deepseek model deepseek-coder [provider.deepseek] base_url https://api.deepseek.com/v1 api_key 你的key注意第三方 API 的兼容性参差不齐。有些接口虽然号称兼容 OpenAI 格式但在流式输出、函数调用等细节上会有差异导致 Codex 报“the gpt-5.6-sol model is not supported when using codex with a...”这类错误。遇到这种情况先确认模型名称是否写对再检查 API 提供方是否支持 Codex 所需的全部接口能力。4. 多模型切换与 openrig 的整合思路4.1 cc switch 与本地代理的冲突排查热搜词里有一条很具体“cc switch local proxy failed while handling codex endpoint /responses. provi”。这说的是用 cc switch 这类工具在 Claude Code 和 Codex 之间切换时本地代理处理 Codex 的/responses端点失败。这个问题的根源通常是代理工具只实现了 Anthropic 的 API 格式没有完整实现 OpenAI 的/responses接口而 Codex 恰好依赖这个端点。解决思路有两个方向。一是换用支持多协议转发的代理工具确保它同时能处理 Anthropic 和 OpenAI 两种格式。二是不用代理直接通过环境变量切换# 切到 Claude Code 配置 export ANTHROPIC_BASE_URL... export ANTHROPIC_API_KEY... # 切到 Codex 配置 export OPENAI_BASE_URL... export OPENAI_API_KEY...我个人的做法是写两个 shell 函数放在.bashrc里use_claude() { export ANTHROPIC_BASE_URLhttps://api.anthropic.com export ANTHROPIC_API_KEYsk-ant-xxx echo Switched to Claude Code } use_codex() { export OPENAI_BASE_URLhttps://api.openai.com/v1 export OPENAI_API_KEYsk-xxx echo Switched to Codex }这样在 tmux 里开两个窗口一个跑 Claude Code一个跑 Codex互不干扰。需要切换时在对应窗口里执行函数即可。4.2 openrig 的目录结构与配置管理把上面这些零散的东西整合起来openrig 的目录结构可以设计成这样~/openrig/ ├── env/ │ ├── claude.env # Claude Code 环境变量 │ └── codex.env # Codex 环境变量 ├── config/ │ ├── claude.json # Claude Code 配置 │ └── codex.toml # Codex 配置 ├── scripts/ │ ├── start-claude.sh │ ├── start-codex.sh │ └── switch.sh └── logs/ ├── claude.log └── codex.logstart-claude.sh的内容#!/bin/bash source ~/openrig/env/claude.env cd ${1:-$HOME/projects} claude 21 | tee -a ~/openrig/logs/claude.logswitch.sh用来在多个模型配置之间切换#!/bin/bash case $1 in claude) source ~/openrig/env/claude.env ;; codex) source ~/openrig/env/codex.env ;; local) source ~/openrig/env/local.env ;; *) echo Usage: switch [claude|codex|local] ;; esac这种结构的好处是配置和代码分离环境变量不会互相污染日志也方便回溯。如果你在团队里用可以把env/目录做成模板每个人填自己的 Key避免把敏感信息提交到仓库。4.3 会话恢复与任务连续性tmux 配合 openrig 的脚本能实现一个很实用的工作流早上到公司tmux attach -t airig昨天没跑完的 Codex 任务还在继续需要切到 Claude Code 做代码审查新开一个窗口source switch.sh claude直接开始。所有会话都在同一个 tmux 服务里Ctrlb w可以看到所有窗口列表。有一个细节值得注意Claude Code 和 Codex 在长时间运行后可能会因为 token 过期或网络波动而卡住。我的做法是在脚本里加一个简单的健康检查每隔一段时间发一个轻量请求确认服务还活着。如果连续失败就自动重启会话并记录日志。这个逻辑不复杂但能省去很多手动排查的时间。5. 常见问题速查与避坑指南5.1 安装与登录类问题问题现象可能原因解决方式error installing 24.21.0: node.js v24.21.0 is not yet released版本号写错或 registry 无此版本改用nvm install 20或官网 LTScodex登录不上回调被拦截或 token 缓存过期删~/.codex缓存重新 OAuthcodex无法加载组织设置多组织账号默认组织无权限配置里显式指定组织 IDyour organization has disabled claude subscription access账号订阅类型不支持确认订阅等级或切换账号npm install -g权限报错混用系统 Node 和 nvm统一用 nvm避免 sudo5.2 运行与代理类问题问题现象可能原因解决方式cc switch local proxy failed while handling codex endpoint /responses代理不支持 OpenAI/responses换代理或直接用环境变量切换codex is ignoring 1 unrecognized configuration setting配置文件字段拼写错误逐行核对config.tomlClaude Code 在 tmux 里认证失败tmux 未加载.bashrc手动source ~/.bashrc本地模型响应慢或超时模型太大或显存不足换小模型或调低并发第三方 API 流式输出中断接口兼容性不完整关闭流式或换 API 提供方5.3 我踩过的三个典型坑第一个坑是 Node.js 版本混用。我一开始用apt装了 Node 18后来又用 nvm 装了 Node 20结果npm全局包路径混乱Claude Code 装到了系统 Node 的目录下nvm 环境里找不到。后来彻底卸载系统 Node只用 nvm 管理问题消失。第二个坑是 tmux 里的环境变量。我在.bashrc里配了 API Key但 tmux 新建会话时没有加载.bashrc导致 Claude Code 一直报认证失败。后来在.tmux.conf里加了set-option -g update-environment ANTHROPIC_API_KEY OPENAI_API_KEY问题解决。第三个坑是 Codex 的配置文件优先级。项目根目录下的.codex.toml会覆盖全局配置但我一开始不知道改了全局配置一直不生效。后来用codex config list才看到实际生效的是项目级配置。这个命令建议大家都记一下排查配置问题时非常有用。5.4 性能与稳定性建议如果你同时跑 Claude Code 和 Codex建议给它们分配不同的工作目录避免文件锁冲突。日志分开写方便排查。tmux 会话建议设置history-limit大一点比如set-option -g history-limit 50000这样翻看长输出时不会丢内容。对于本地模型LM Studio 的 GPU 加速要确认开启否则推理速度会慢到无法忍受。在 Ubuntu 上还需要确认 CUDA 驱动版本和 LM Studio 要求的版本匹配不匹配时 LM Studio 会回退到 CPU速度直接掉一个数量级。最后再分享一个小技巧如果你经常需要在 Claude Code 和 Codex 之间复制粘贴代码可以在 tmux 里开启鼠标模式set -g mouse on然后用鼠标选中复制。虽然终端里的复制粘贴一直是个麻烦事但开启鼠标模式后至少不用记那么多快捷键了。