openrig 实战：Node.js + tmux 搭建 Claude Code 与 Codex 稳定开发环境

1. 从"openrig"这个名字说起：它到底想解决什么问题

第一次看到openrig这个词，我脑子里蹦出来的画面是矿场里的钻井平台——rig 在英文里本来就有"装备、装置、平台"的意思，open 则代表开放。把这两个词拼在一起，再结合它周围那一圈热词（Claude Code、Codex、Node.js、tmux），基本可以判断出：这是一个围绕命令行 AI 编程助手搭建的开放工作台/脚手架类项目，目标是把 Claude Code、Codex 这类 CLI 形态的智能编码工具，和 Node.js 运行时、tmux 会话管理捏合成一套可复用、可切换、可远程挂载的开发环境。

为什么我敢这么判断？因为热词列表里几乎全是"安装踩坑"和"配置报错"：node.js v24.21.0 is not yet released、cc switch local proxy failed while handling codex endpoint /responses、codex is ignoring 1 unrecognized configuration setting、your organization has disabled claude subscription access……这些不是产品功能词，而是真实用户在落地过程中撞到的墙。一个叫 openrig 的项目如果出现在这个语境里，它十有八九就是来"填这些坑"的——把散落在各处的安装步骤、模型接入配置、会话保持方案收敛成一套开箱即用的骨架。

我自己的判断是，openrig 的核心价值不在"又一个 AI 工具"，而在于编排（orchestration）。单个 Claude Code 或 Codex 谁都会装，难的是：怎么在 Ubuntu 服务器上让它们长期跑着不掉线？怎么在本地模型（比如 LM Studio）和云端模型之间来回切？怎么让 VS Code 里的终端和后台 tmux 会话共享同一套配置？这些问题单靠官方文档是拼不齐答案的，必须有人把碎片粘起来。openrig 要做的，大概率就是这块"胶水"。

这篇文章我打算按"一个真实从业者从零搭这套环境"的顺序来写：先讲清楚它背后的技术栈为什么是这几个，再拆 Node.js 这个地基怎么打才不翻车，然后是 Claude Code 和 Codex 两条主线的接入细节，接着是 tmux 会话保持这个最容易被忽视但最影响体验的环节，最后聊聊模型切换和本地模型接入的实战。全程会带上我踩过的坑和验证过的参数，能直接抄作业。

提示：本文所有命令和配置都基于 Linux（Ubuntu 22.04/24.04）和 macOS 的通用实践，Windows 用户建议走 WSL2，原生 Windows 下 tmux 生态不完整，后面会单独说。

2. 为什么这套栈偏偏是 Node.js + tmux + CLI 助手

2.1 Node.js 不是可选项，而是硬性地基

很多人装 Claude Code 或 Codex 时第一反应是"我系统里不是有 node 吗"，然后node -v一看是 v16 或者 v18，直接开装，结果报一堆engine不匹配。这里必须说清楚：当前主流的 CLI 形态 AI 编程助手，绝大多数是 npm 包分发，对 Node.js 版本有明确下限。热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型的版本管理混乱——用户想装一个还没正式发布的版本号，包管理器直接拒绝。

我的经验是：不要追最新，追 LTS。Node.js 的发布节奏是偶数版本进 LTS，奇数版本是实验性的。你在生产环境或者日常开发环境里，应该锁在当前的 LTS 线上。截至我写这篇内容时，Node.js 20.x 和 22.x 是稳妥选择，20.x 更保守，22.x 性能更好。热词里出现ubuntu安装node.js 20+说明很多人已经意识到 20 是分水岭。

为什么版本这么敏感？因为 CLI 助手内部大量依赖现代 JS 特性（顶层 await、fetch API 原生支持、structuredClone 等），这些在 Node 18 之前要么没有要么是实验性的。你用一个 v16 去跑，轻则警告，重则直接 crash 在启动阶段，而且报错信息往往指向依赖包内部，让你误以为是工具本身的问题。

2.2 tmux 解决的是"AI 助手会掉线"这个致命体验问题

这是最容易被新手忽略的一环。你在 SSH 里跑claude或者codex，一旦网络抖动、笔记本合盖、终端窗口误关，进程就跟着会话一起没了。AI 编程助手经常要跑长任务——读大文件、分析整个仓库、生成大段代码——跑到一半断了，前面的上下文全丢，这种挫败感比报错还难受。

tmux 的作用就是把进程和终端会话解耦。你开一个 tmux 会话，在里面跑助手，然后 detach（Ctrl+b再按d），进程继续在后台跑。下次 SSH 上来tmux attach，界面原封不动。热词里tmux和claude code如何直接执行终端命令挨在一起，说明大家已经意识到：AI 助手要真正"干活"，得让它在一个持久化的终端环境里操作，而不是每次对话都从零开始。

我个人的习惯是给每个项目开一个独立的 tmux 会话，命名规则是项目名-用途，比如myapp-ai、myapp-dev。这样切项目的时候tmux ls一眼就能看清哪个会话在干什么，不会串。

2.3 为什么是"开放"（open）——多模型、多工具的自由切换

openrig里的 open，我理解有两层含义。第一层是开放的工具链：不绑定某一家，Claude Code 能用，Codex 也能用，将来别的 CLI 助手接进来也不违和。第二层是开放的模型后端：既可以用官方订阅，也可以接第三方 API，还能指向本地跑的模型（热词里claude code 调用lmstudio的本地模型、codex接入deepseek都是这个诉求）。

这就引出了整个栈里最复杂、最容易出问题的部分——模型接入与切换。官方订阅有组织策略限制（your organization has disabled claude subscription access），第三方 API 有端点兼容问题（cc switch local proxy failed while handling codex endpoint /responses），本地模型有协议差异。openrig 如果真能把这些统一起来，那它的价值就立住了。

下面这张表是我梳理的三种接入方式对比，后面章节会逐个展开：

3. Node.js 环境搭建：别让地基拖垮整栋楼

3.1 用 nvm 而不是系统包管理器，这是血泪教训

Ubuntu 上apt install nodejs装出来的版本往往落后好几个大版本，而且升级极其麻烦。我强烈建议用nvm（Node Version Manager）来管理 Node.js。理由很直接：AI 助手工具更新频繁，有时候新版本要求更高的 Node，有时候某个依赖又和最新 Node 不兼容，你需要能秒切版本。

安装 nvm 的标准姿势：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

装完记得重开终端，或者source ~/.bashrc。然后验证：

command -v nvm

如果输出nvm就对了。注意这里用command -v而不是which，因为 nvm 是个 shell 函数，which找不到它，这是新手常犯的误判。

接着装 LTS：

nvm install --lts nvm use --lts nvm alias default 'lts/*'

最后那行alias default很关键，它保证你每次新开终端默认就用 LTS，不用手动nvm use。我见过太多人装完 nvm 忘了设默认，结果新终端里 node 又变回系统那个老版本，然后一脸懵地问"我不是装了吗"。

3.2 版本校验与常见报错对照

装完之后跑一遍：

node -v npm -v

正常应该看到类似v20.x.x和10.x.x。如果node -v报的是系统版本，说明 nvm 没生效，检查~/.bashrc或~/.zshrc里有没有 nvm 的初始化脚本。

热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released值得单独说。这个报错的本质是：你指定的版本号在 nvm 的远程版本列表里不存在。可能是你记错了版本号，也可能是那个版本还在 nightly 阶段没进正式列表。解决办法是先nvm ls-remote看看有哪些可用版本，别凭记忆瞎填。我一般会nvm ls-remote | grep v20过滤一下，确认了再装。

还有一个高频问题：npm install -g装全局包时权限报错。用 nvm 的话基本不会遇到，因为全局包装在用户目录下。如果你还在用系统 node，就会碰到EACCES权限问题，然后有人教你sudo npm install -g——千万别这么干，sudo 装的全局包会带来一堆权限和路径混乱，后患无穷。正确做法就是换 nvm。

3.3 镜像源配置：国内环境的必要优化

如果你在国内网络环境，npm 官方源拉包会很慢甚至超时。配置镜像源：

npm config set registry https://registry.npmmirror.com

验证：

npm config get registry

这个设置对后续安装 CLI 助手影响很大。我实测过，不配镜像源的情况下，装一个依赖较多的 CLI 工具可能要几分钟甚至卡死，配了之后通常几十秒搞定。注意镜像源偶尔会有同步延迟，如果某个包版本拉不到，临时切回官方源npm config set registry https://registry.npmjs.org再试。

注意：镜像源只影响 npm 包下载，不影响 AI 助手运行时调用模型 API 的网络。这两件事经常被混为一谈，实际上完全独立。

4. Claude Code 与 Codex 的接入：两条主线，各有各的脾气

4.1 Claude Code 的安装与首次配置

Claude Code 的安装本身不复杂，全局装即可：

npm install -g @anthropic-ai/claude-code

装完在项目目录里直接敲claude就能启动。第一次启动会引导你完成认证。这里有个关键分叉：用官方订阅还是用 API Key。如果你有 Claude 的订阅，走订阅认证体验最顺；如果走 API Key，需要设置环境变量。

我遇到最多的问题是热词里那条your organization has disabled claude subscription access for claude code。这个报错的含义是：你的账号所属组织在管理后台关闭了 Claude Code 的订阅访问权限。这不是你本地配置的问题，是账号策略层面的限制。解决办法要么找组织管理员开通，要么改用 API Key 方式接入。很多人在这里折腾半天本地配置，方向完全错了。

VS Code 集成方面，热词里claude code for vs code、vscode配置claude code说明大家很关心编辑器内使用。我的建议是：先在纯终端里把 Claude Code 跑通，再考虑 VS Code 集成。因为 VS Code 的集成终端本质上还是终端，底层问题不解决，套个编辑器壳子照样报错。终端跑通了，VS Code 里无非是打开集成终端敲同样的命令，或者装官方扩展。

4.2 Codex 的安装与"无法加载组织设置"排查

Codex 的安装路径类似，也是 npm 全局包。热词里codex安装 windows桌面版、codex安装教程、codex cli都指向同一个诉求：怎么装、怎么登。

codex无法加载组织设置这个报错我专门研究过。它通常出现在登录阶段，本质是客户端尝试拉取你账号的组织级配置时失败了。可能原因有三类：网络到认证端点的连通性问题、账号本身没有加入任何组织、客户端版本过旧导致接口不匹配。排查顺序我建议这样：

1. 先确认客户端是最新版：npm update -g更新全局包。
2. 检查登录状态，必要时登出重登。
3. 如果还是不行，看是不是网络层面对认证域名的访问有问题。

codex is ignoring 1 unrecognized configuration setting. check for typos or d...这条是配置文件的字段名写错了。Codex 的配置文件对字段名大小写和拼写很敏感，多一个字母少一个字母都会被忽略并警告。我的做法是：改配置前先备份，改完立刻看启动日志有没有 warning，别等到功能不生效才回头找。

4.3 两个助手共存时的配置隔离

如果你像我一样 Claude Code 和 Codex 都要用，最大的坑是配置互相污染。它们各自的配置文件、环境变量、认证缓存如果混在一起，会出现"昨天还好好的今天突然登不上"的灵异现象。

我的做法是给每个工具独立的配置目录和环境变量前缀。启动不同工具前，用 shell 函数或者 direnv 切换环境。举个简单的思路：

# 在 ~/.bashrc 里定义切换函数 use_claude() { export AI_TOOL=claude export ANTHROPIC_API_KEY="你的key" } use_codex() { export AI_TOOL=codex export OPENAI_API_KEY="你的key" }

这样切工具的时候环境变量是干净的，不会串。虽然土，但极其有效。我踩过一次坑：两个工具都读同一个API_KEY变量名，结果 Codex 拿着 Claude 的 key 去请求，报了一堆看不懂的认证错误，排查了半小时才发现是变量名冲突。

5. tmux 会话管理：让 AI 助手真正"挂得住"

5.1 基础会话操作与命名规范

tmux 的核心操作就几个，但必须练到肌肉记忆：

tmux new -s myapp-ai # 新建名为 myapp-ai 的会话 tmux ls # 列出所有会话 tmux attach -t myapp-ai # 重新接入 tmux kill-session -t myapp-ai # 杀掉会话

会话内：Ctrl+b是前缀键，按完松开再按d是 detach，按"是横向分屏，按%是纵向分屏。

我的命名规范前面提过：项目名-用途。为什么强调命名？因为当你同时跑三四个项目、每个项目又有 AI 会话和开发会话时，tmux ls里一堆0、1、2你根本分不清谁是谁。命名是成本最低的秩序。

5.2 让 AI 助手在 tmux 里稳定长跑的关键设置

默认 tmux 有个坑：滚动缓冲区太小。AI 助手输出动辄几百上千行，默认 buffer 很快就滚没了，你想回看前面的分析结果发现找不到了。在~/.tmux.conf里加：

set -g history-limit 50000

这个数字我设的是 5 万行，够用且不吃太多内存。有人设 10 万甚至更多，除非你真有极端需求，否则没必要。

另一个关键设置是鼠标支持：

set -g mouse on

开了之后可以用鼠标滚轮翻历史、点击切换 pane，对从 GUI 终端过来的人极其友好。不开的话你得用Ctrl+b加方向键，效率差很多。

还有一个我强烈推荐的：保持窗口编号不重排。

set -g renumber-windows on

以及关闭那个烦人的自动重命名：

set -g allow-rename off

这些设置加起来，你的 tmux 就从"能用"变成"好用"。

5.3 断线重连与多设备接续的实战场景

tmux 最爽的场景是：你在公司台式机上开着 AI 会话跑一个大重构任务，下班回家用笔记本 SSH 上来tmux attach，任务还在跑，输出还在，上下文完整。这种体验一旦用过就回不去了。

但有个细节要注意：不同设备的终端尺寸不一样，attach 上去之后界面可能错乱。解决办法是 attach 之后按Ctrl+b再按:resize-window -A，或者干脆在配置里加：

set -g aggressive-resize on

这个设置让 tmux 根据当前实际连接的客户端调整窗口大小，多设备切换时体验好很多。

提示：如果你在 tmux 里跑 AI 助手时发现中文显示乱码，检查两处——终端本身的 locale 设置（locale命令看是不是 UTF-8），以及 tmux 配置里有没有set -g default-terminal "screen-256color"。这两个都对上，中文基本不会出问题。

6. 模型切换与本地模型接入：openrig 最硬核的部分

6.1 第三方 API 接入的端点兼容问题

热词里cc switch local proxy failed while handling codex endpoint /responses这条报错信息量很大。它说明用户在用某种代理/切换工具（cc switch）把 Codex 的请求转发到第三方端点时，/responses这个路径处理失败了。

这里的核心矛盾是：不同模型提供商的 API 路径和请求体格式不完全一致。Codex 期望的端点是/responses，但很多第三方兼容 API 提供的是/v1/chat/completions（OpenAI 经典格式）。代理工具要做的是协议转换，转换规则没配对，就会在/responses这个环节挂掉。

我的排查思路是：

1. 先确认第三方 API 实际暴露的端点路径是什么，用 curl 直接测。
2. 再看代理工具的配置里，路径映射规则写对没有。
3. 最后看请求体字段，有些提供商不支持stream、tools等字段，需要代理层过滤。

# 直接测试第三方端点是否通 curl -X POST https://你的端点/v1/chat/completions \ -H "Authorization: Bearer 你的key" \ -H "Content-Type: application/json" \ -d '{"model":"模型名","messages":[{"role":"user","content":"hi"}]}'

这个 curl 能通，说明端点本身没问题，问题在代理配置；不通，说明端点或 key 有问题。这一步能帮你快速定位问题在哪一层。

6.2 本地模型接入：LM Studio 与协议适配

claude code 调用lmstudio的本地模型这个需求很典型：数据敏感、不想出本机、或者就是想省钱。LM Studio 本地起一个服务，默认监听http://localhost:1234，暴露的是 OpenAI 兼容接口。

接入的关键是把 Claude Code 或 Codex 的请求指向这个本地端点。通常通过环境变量设置 base URL：

export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="lm-studio" # 本地模型随便填个非空值

注意本地模型有几个现实约束，必须提前有心理预期：

• 上下文长度：本地小模型的上下文窗口通常远小于云端模型，喂大文件会直接超限。
• 推理速度：取决于你的显卡，7B 模型在消费级显卡上还行，70B 就得很好的硬件。
• 工具调用能力：AI 编程助手重度依赖 function calling / tool use，很多本地小模型这块能力弱，会导致助手"不会用工具"，表现得很笨。

我的建议是：本地模型适合做轻量问答和代码解释，真要跑复杂的仓库级重构，还是云端模型靠谱。别指望一个 7B 本地模型能干 Claude 或 GPT 级别旗舰模型的活。

6.3 多模型切换的配置管理策略

当你同时要接官方、第三方、本地三种后端时，配置管理就成了核心问题。我的做法是用独立的配置文件 + 环境变量注入，而不是把所有配置堆在一个文件里。

具体来说，为每种后端建一个 env 文件：

# ~/.ai-config/claude-official.env export ANTHROPIC_API_KEY="sk-ant-xxx" # ~/.ai-config/claude-local.env export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="lm-studio" # ~/.ai-config/codex-thirdparty.env export OPENAI_BASE_URL="https://第三方端点/v1" export OPENAI_API_KEY="sk-xxx"

切换的时候source对应的文件即可。这样每个后端的配置互不干扰，出问题也好定位。我还会在文件顶部加注释写明这个配置的用途和最后验证日期，过一段时间回头看不会懵。

7. 那些让我熬夜的报错，以及它们真正的根因

7.1 "model is not supported" 类报错的通用排查法

热词里{"detail":"the 'gpt-5.6-sol' model is not supported when using codex with a..."}这条报错，本质是你请求的模型名，当前接入的后端不认识。可能原因：模型名拼错了、后端根本没上这个模型、或者后端用的是别名而你用了全名。

排查三步走：

1. 列出后端实际支持的模型列表（大多数兼容 API 有/v1/models端点）。
2. 对比你配置里写的模型名和列表里的名字，逐字符核对。
3. 如果后端支持别名映射，在配置里做映射。

curl https://你的端点/v1/models -H "Authorization: Bearer 你的key"

这个命令能直接告诉你后端有哪些模型可用，比猜快得多。

7.2 认证类报错：区分"本地问题"和"账号问题"

codex登录不上、your organization has disabled...这类报错，新手最容易在本地配置上死磕。我的经验是先判断问题层级：

• 如果是"登录不上"，先看网络能不能到认证端点。
• 如果是"组织禁用了某功能"，这是账号策略，本地怎么改都没用。
• 如果是"key 无效"，检查 key 有没有过期、有没有复制时带空格。

判断方法很简单：换一个已知可用的账号或 key 试一下。如果换了就好，说明是账号问题；换了还不行，才是本地环境问题。这个"控制变量法"能帮你省下大量瞎折腾的时间。

7.3 配置文件警告：别忽视那些"ignoring"提示

codex is ignoring 1 unrecognized configuration setting这种警告，很多人直接无视，觉得"能用就行"。但我的经验是：配置警告往往是功能不生效的前兆。今天忽略一个字段，明天可能就发现某个功能莫名其妙不工作，回头找原因发现就是那个被忽略的字段。

我的习惯是每次改完配置，启动时把日志从头到尾看一遍，有 warning 就当场解决。配置文件的字段名、缩进、引号都有讲究，YAML 和 JSON 对格式的容忍度完全不同。YAML 里一个 tab 就能让整个文件解析失败，JSON 里多一个逗号直接报错。

注意：改配置文件前一定先备份。我见过太多人改崩了配置又没备份，最后只能重装。cp config.yaml config.yaml.bak这一秒钟的操作，能救你半小时。

8. 我实际搭这套环境时总结的几条硬经验

第一，先跑通最小闭环，再谈优化。不要一上来就搞多模型切换、本地模型接入、VS Code 集成全套。先用官方订阅把 Claude Code 在 tmux 里跑通，确认能正常对话、能执行命令，再往上加东西。每加一层都验证一次，出问题能立刻定位到是哪一层引入的。

第二，版本信息永远记录在案。Node 版本、CLI 工具版本、tmux 版本，这些在你排查问题时是重要线索。我习惯在项目根目录放一个ENV.md，记录当前环境的完整版本快照。出问题时对比一下"上次能用的时候是什么版本"，往往一眼就能看出是不是某次升级引入的。

第三，网络问题占报错的一半以上。AI 助手要连模型 API，网络不通、DNS 解析慢、代理配置错，都会表现为各种奇怪的报错。遇到看不懂的报错，先curl测一下目标端点通不通，能排除掉一大半问题。

第四，tmux 会话要定期清理。跑久了一堆僵尸会话占着资源，tmux ls一看十几个。我每周清理一次，tmux kill-server一把梭（确认没有正在跑的重要任务的前提下）。干净的环境让人心情好，排查问题也清爽。

第五，本地模型别抱太高期望。我试过用本地 7B 模型接 Claude Code，简单的代码解释还行，一旦涉及多文件分析、工具调用，表现就明显拉胯。本地模型适合特定场景（数据敏感、离线），不适合当主力。认清这一点，能省下很多"为什么它这么笨"的困惑。

这套 openrig 思路的核心，其实就是把"装工具"这件事从一次性劳动变成可维护的工程。工具会更新，模型会换代，但只要你把环境分层管好、配置隔离清楚、会话保持稳定，换什么工具都是改几个环境变量的事。我现在换一个新项目，从零到 AI 助手跑起来，基本十分钟内搞定，靠的就是这套已经踩平了坑的流程。