1. openrig 到底想解决什么问题
第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 “rig” 在英文里常指设备支架、矿机架或者测试台。但结合它周围高频出现的关键词——Claude Code、Codex、Node.js、tmux——就能判断出来，这是一个围绕 AI 编程助手工作流搭建的本地运行环境整合方案。说得再直白一点：它要处理的是“怎么让 Claude Code 和 Codex 这类命令行 AI 工具，在一台机器上稳定、可切换、可远程地跑起来”这件事。
我自己从 Claude Code 早期版本就开始用，也经历过 Codex CLI 刚放出时各种配置报错的阶段。那会儿最头疼的不是模型能力，而是环境本身：Node.js 版本不对、终端会话一关任务就断、多个模型供应商的 API 配置互相覆盖、Windows 和 Ubuntu 下行为不一致。openrig 这个标题背后，其实指向的是一套“把 AI 编程助手当成正经开发环境来管理”的思路，而不是装完就用、用完就扔的临时脚本。
它适合谁？三类人最需要：第一类是想在本地把 Claude Code 或 Codex 跑通、但被 Node.js 版本和安装报错卡住的新手；第二类是需要同时接入多个模型供应商（比如 DeepSeek、Qwen、GLM）做对比或切换的进阶用户；第三类是想把 AI 编程助手放到远程服务器上、通过 tmux 保持长会话的运维型开发者。这三类人的共同点是：他们要的不是“能跑一次”，而是“每天都能稳定跑”。
所以这篇内容我会围绕 openrig 这个核心，把环境搭建、工具选型、会话管理、模型切换、常见报错这几块拆开讲。里面既有我踩过的坑，也有实测下来比较稳的做法。你不需要完全照抄，但每一步背后的“为什么”我会讲清楚，这样你遇到变体场景也能自己判断。
2. 环境底座：Node.js 与终端会话的选型逻辑
2.1 为什么 Node.js 版本是第一个拦路虎
Claude Code 和 Codex CLI 本质上都是 Node.js 写的命令行工具，所以 Node.js 是绕不开的底座。热搜里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型症状——你照着某个教程敲了安装命令，结果版本号根本不存在，或者镜像源里还没同步。这不是你操作错了，而是教程写死了版本号，而 Node.js 的发布节奏和镜像同步之间有延迟。
我的建议是：永远不要手动指定一个精确到补丁号的版本去装，除非你有明确的兼容性需求。正确做法是装 LTS 大版本，让它自己解析到当前可用的最新补丁。在 Ubuntu 上，用 NodeSource 的安装脚本时，只给主版本号：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这里的20.x就是让包管理器去挑 20 系列里可用的版本。Windows 用户更简单，直接去 Node.js 官网下载 LTS 的.msi安装包，别去第三方站点下“绿色版”，那些往往缺 npm 或者 PATH 配置不全，后面 Claude Code 装不上你还得回头排查。
装完必须验证两件事：
node -v npm -v两个都要有输出，且 node 版本是偶数开头的大版本（18、20、22 这类 LTS）。如果npm -v报错，说明安装不完整，别急着往下走，先把 Node.js 卸干净重装。我见过太多人卡在“claude code 安装失败”，最后发现是 npm 本身就没配好。
提示：如果你机器上已经有旧版 Node.js，先用
node -v看清楚。多个版本共存时，优先用 nvm 管理，避免系统级 Node.js 和用户级 Node.js 打架。
2.2 tmux 为什么是 AI 编程助手的“保命符”
tmux 出现在热搜里不是偶然。Claude Code 和 Codex 这类工具经常要跑长任务——比如让它读一个大仓库、生成一批代码、或者持续对话。如果你直接在 SSH 终端里跑，网络一抖、笔记本一合盖，会话就断了，任务半途而废，之前烧的 token 也白费。
tmux 解决的就是这个问题：它把会话和终端窗口解耦。你连上去，创建一个会话，任务在里面跑；你断开，会话还在服务器上活着；你重新连上，tmux attach回去，一切照旧。对于把 AI 编程助手放在远程开发机上的用户，这是刚需。
基本操作就三条命令，记住就够用：
tmux new -s rig # 新建一个叫 rig 的会话 tmux ls # 列出所有会话 tmux attach -t rig # 重新接入 rig 会话在会话里，Ctrl+b然后按d是“分离”，也就是暂时退出但保持运行。这个组合键我建议形成肌肉记忆。很多人第一次用 tmux 会慌，因为不知道怎么就“卡住”了，其实就是进了 tmux 的控制模式，按d分离或者按方向键操作窗格即可。
注意：tmux 会话里的环境变量和你登录 shell 的环境变量可能不完全一致。如果你在
.bashrc里配了 API Key，tmux 里读不到，那就把配置放到.profile或者.bash_profile里，确保登录时加载。
2.3 openrig 思路下的目录与权限规划
openrig 如果只是“装几个工具”，那价值有限。它真正的价值在于把 AI 编程助手的工作目录、配置目录、日志目录分开管理。我自己的做法是建一个统一的工作根目录，比如~/airig，下面分三块：
~/airig/workspace：放实际要处理的代码仓库，Claude Code 和 Codex 都在这里启动。~/airig/config：放各工具的配置文件、API Key 的环境变量文件。~/airig/logs：放会话日志，方便回溯某次任务到底发生了什么。
这样做的好处是，当你需要迁移机器或者备份时，直接打包~/airig就行，不会把系统里散落各处的配置漏掉。权限方面，config目录建议chmod 700，因为里面可能有 API Key。别小看这一步，我见过有人把 Key 写在项目根目录的.env里，然后不小心提交到公开仓库，后果很麻烦。
3. Claude Code 与 Codex 的安装与配置实操
3.1 Claude Code 安装：从 npm 到首次运行
Claude Code 的安装本身不复杂，复杂的是网络和账号状态。标准安装命令是：
npm install -g @anthropic-ai/claude-code装完之后，在项目目录里直接敲claude就能启动。但热搜里那条your organization has disabled claude subscription access for claude code说明，很多人卡在账号权限上。这不是安装问题，而是你的账号所属组织关闭了 Claude Code 的访问权限。遇到这个，先确认你用的是个人账号还是组织账号，组织账号需要管理员在后台开启对应权限。
另一个高频问题是note: claude code might not be available in your country。这个提示出现时，先别急着怀疑安装，它更多是服务可用性层面的提示。我的经验是：先把本地环境跑通，确认claude命令能启动、能读到配置，再去看账号和服务状态。环境没通之前，纠结服务提示没有意义。
首次运行 Claude Code，它会引导你做一些初始化配置。这里有个细节：工作目录很重要。Claude Code 默认会读取当前目录作为上下文，所以你要先cd到目标项目再启动。如果你在 home 目录直接跑，它可能会去扫描一堆无关文件，既慢又浪费上下文。
3.2 Codex 安装：CLI 与桌面版的取舍
Codex 的安装路径比 Claude Code 稍微多一点选择。热搜里同时出现了codex cli、codex 安装 windows桌面版、codex安装包，说明大家在纠结用哪种形态。我的判断标准很简单：
- 如果你主要在终端里工作，习惯命令行，选Codex CLI。它和 Claude Code 的使用方式接近，都是终端里对话、执行命令。
- 如果你想要图形界面、点点鼠标就能用，选桌面版。但桌面版在自动化和脚本化方面不如 CLI 灵活。
CLI 版一般也是通过 npm 安装，装完后用codex命令启动。启动后第一件事是登录，热搜里的codex登录和codex无法加载组织设置往往连在一起——登录成功了，但组织配置拉不下来。这种情况通常是账号权限或者网络请求被拦截。我的处理顺序是：先确认能登录，再看组织设置；如果组织设置一直加载失败，先用个人配置把本地流程跑通，别在组织层面死磕。
Codex 还有一个常见提示：codex is ignoring 1 unrecognized configuration setting. check for typos or d...。这是配置文件里有它不认识的字段。别慌，这通常不影响运行，但你应该去配置文件里把那个字段找出来删掉或者改对。配置文件一般是 JSON 或 TOML 格式，用编辑器打开，对照官方文档的字段名逐个核对。拼写错误是高频原因，比如把model写成modle。
3.3 多模型接入：DeepSeek、Qwen、GLM 的切换思路
热搜里codex接入deepseek和使用cc switch 接入 deepseek v4, qwen, glm等模型指向同一个需求：不想只用一个模型，想按任务切换。这个需求很实际——写代码可能 Claude 更稳，做中文理解可能 Qwen 更顺，成本敏感时 DeepSeek 更划算。
实现多模型接入，核心是两件事：一是每个供应商的 API 端点和 Key 要分开管理，二是要有一个切换机制。切换机制有两种常见做法：
第一种是环境变量切换。把不同供应商的配置写成不同的 env 文件，启动前 source 对应的文件。比如：
# deepseek.env export API_BASE="https://api.deepseek.com" export API_KEY="sk-xxxx" # qwen.env export API_BASE="https://dashscope.aliyuncs.com" export API_KEY="sk-yyyy"启动前source deepseek.env再跑 Claude Code 或 Codex。这种方式简单直接，缺点是每次切换要手动 source。
第二种是用切换工具，也就是热搜里提到的 cc switch 这类方案。它的思路是维护一份配置文件，里面列出多个供应商，通过命令或界面选择当前激活的。这种方式适合频繁切换的人，但要注意工具本身是否还在维护、配置格式是否和你的 Claude Code / Codex 版本兼容。
提示：无论用哪种方式，API Key 都不要硬编码在项目代码里。放在独立的 env 文件，并且把该文件加入
.gitignore。这是最基本的安全习惯。
3.4 VS Code 集成：让 AI 助手贴着代码走
vscode配置claude code和vscode接入claude code是很多人的诉求，因为纯终端操作对不习惯命令行的人有门槛。VS Code 集成的好处是：你可以在编辑器里直接看到 AI 修改了哪些文件，diff 一目了然，不用在终端和编辑器之间来回切。
集成的思路通常是：在 VS Code 的集成终端里运行 Claude Code 或 Codex，这样它就在当前项目目录下工作，编辑器能实时感知文件变化。更进一步的集成是通过扩展或任务配置，把启动命令绑定到快捷键。我的做法是在.vscode/tasks.json里加一个任务，一键在集成终端启动 Claude Code：
{ "version": "2.0.0", "tasks": [ { "label": "Start Claude Code", "type": "shell", "command": "claude", "problemMatcher": [] } ] }这样按Ctrl+Shift+B就能启动，省去手敲命令。注意，集成终端里的环境变量继承自 VS Code 启动时的环境，如果你在.bashrc里配了 Key，而 VS Code 是从桌面图标启动的，可能读不到。解决办法是从终端里用code .启动 VS Code，这样环境变量就带进去了。
4. 会话管理、远程运行与稳定性保障
4.1 用 tmux 把 AI 任务变成“后台作业”
前面讲了 tmux 的基本操作，这里讲怎么把它和 AI 编程助手结合成一套稳定工作流。我的标准流程是这样的：
- SSH 登录开发机。
tmux new -s rig创建会话。cd ~/airig/workspace/项目名进入目标项目。- 启动 Claude Code 或 Codex，开始任务。
- 任务跑起来后，
Ctrl+b d分离，去干别的。 - 过一段时间
tmux attach -t rig回来看进度。
这套流程的关键在于：任务的生命周期不再依赖你的网络连接。哪怕你在地铁上信号断了，服务器上的会话和 AI 任务照常跑。对于需要长时间生成代码或分析大仓库的场景，这是唯一靠谱的做法。
还有一个进阶技巧：在 tmux 里开多个窗格，一个跑 Claude Code，一个跑 Codex，一个用来看日志或跑测试。Ctrl+b %是垂直分屏，Ctrl+b "是水平分屏。这样你可以让两个 AI 助手同时处理不同任务，或者一个写代码一个做 review，效率提升很明显。
4.2 远程开发机上的环境一致性
把 AI 编程助手放在远程开发机上，最大的好处是环境统一。你本地是 Windows、Mac 还是 Linux 都不重要，远程那台机器是固定的 Ubuntu，所有配置一次配好，换本地设备不用重配。但这里有个坑：远程机器的 Node.js 版本和本地可能不一致，导致同一个项目在两边行为不同。
我的做法是：远程机器上固定用 LTS 版本，并且把版本号记在~/airig/README里。如果团队多人用同一台开发机，最好用 nvm 给每个人配独立的 Node.js 版本，避免互相干扰。nvm 的安装和切换很简单：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20装完后node -v确认是 20.x。这样即使系统里还有别的 Node.js，你的会话里用的也是 nvm 管理的这个。
4.3 会话日志与问题回溯
AI 编程助手跑任务时，输出往往很长，终端滚动缓冲有限，出了问题想回头看前面的内容很麻烦。tmux 自带日志功能，可以把整个会话的输出写到文件：
tmux new -s rig -l -f ~/airig/logs/rig-$(date +%Y%m%d).log这样每次会话的完整输出都留档。出问题时，直接去日志文件里搜关键字，比在终端里翻历史高效得多。我一般会按日期命名日志，一周清理一次，避免占满磁盘。
另外，Claude Code 和 Codex 自身也可能有日志或历史记录功能。花点时间看看它们的配置项，把历史记录打开，这样即使 tmux 日志没开，也能从工具自身的历史里找回上下文。
5. 常见报错与排查速查
5.1 安装类报错
| 报错信息 | 可能原因 | 处理方式 |
|---|---|---|
node.js v24.21.0 is not yet released | 教程写死了不存在的版本号 | 改用 LTS 大版本安装，如setup_20.x |
npm: command not found | Node.js 安装不完整 | 重装 Node.js，确认 npm 一起装上 |
permission denied安装全局包 | 没有全局安装权限 | 用 nvm 管理 Node.js，避免 sudo npm |
claude code 安装失败无具体信息 | 网络或镜像源问题 | 换 npm 镜像源，或检查网络连通性 |
5.2 运行类报错
| 报错信息 | 可能原因 | 处理方式 |
|---|---|---|
your organization has disabled... | 组织账号权限未开 | 联系管理员开启，或改用个人账号 |
codex无法加载组织设置 | 组织配置拉取失败 | 先用个人配置跑通本地流程 |
unrecognized configuration setting | 配置文件字段拼写错误 | 对照官方文档核对字段名 |
cc switch local proxy failed | 切换工具的本地代理异常 | 检查切换工具配置，或改用手动 env 切换 |
might not be available in your country | 服务可用性提示 | 先确认本地环境正常，再排查账号 |
5.3 我踩过的几个坑
第一个坑是在 Windows 上用 Git Bash 跑 Claude Code。Git Bash 的环境和原生 Linux 有差异，某些路径处理和权限行为不一致，导致工具找不到配置文件。后来我改用 WSL2，问题消失。如果你在 Windows 上遇到莫名其妙的“找不到文件”或“权限错误”，优先考虑 WSL2，而不是在 Git Bash 里死磕。
第二个坑是tmux 里 API Key 读不到。原因前面提过，.bashrc在非交互式 shell 里不加载。解决办法是把 Key 配置放到.profile，或者在 tmux 启动后手动 source 一次。我现在的做法是写一个~/airig/env.sh，里面 export 所有 Key，然后在 tmux 会话里source ~/airig/env.sh，一步到位。
第三个坑是同时装 Claude Code 和 Codex 后命令冲突。两个工具如果都往 PATH 里写同名命令，或者配置文件互相覆盖，就会出现“昨天还好好的，今天启动就报错”。我的做法是给每个工具单独的环境变量前缀，配置文件也分开放，互不干扰。
6. 把 openrig 用成日常习惯
环境搭好只是开始，真正决定效率的是日常怎么用。我现在的习惯是：每天早上到工位，先 SSH 上开发机，tmux attach回昨天的会话，看看有没有跑完的任务；然后开一个新窗格，把当天要处理的仓库拉下来，启动 Claude Code 做一轮代码梳理。需要对比模型时，切到另一个窗格用 Codex 接 DeepSeek 跑同样的任务，看两边输出差异。
这套流程跑顺之后，最大的感受是：AI 编程助手不再是“偶尔用一下的工具”，而是开发环境的一部分。它像你的编译器和调试器一样，随时在那儿，随时能用。openrig 这个标题背后的价值，也正在于此——它不是教你装一个软件，而是帮你把一整套 AI 辅助开发的工作方式固化下来。
如果你刚开始搭，别追求一次配到完美。先把 Node.js 和 tmux 这两个底座弄稳，再把 Claude Code 或 Codex 其中一个跑通，然后慢慢加第二个模型、加日志、加 VS Code 集成。每加一层都验证一次，出问题容易定位。一上来就全量配置，报错时你根本不知道是哪一层的问题。
最后分享一个我用了很久的小技巧：在~/airig下放一个start.sh，把进入目录、source 环境变量、启动 tmux 这几步串起来。每次开工就执行它，省去重复敲命令。脚本不用复杂，能跑通就行，关键是让“开始工作”这个动作足够顺滑，顺滑到你愿意每天都用。
