1. 从“openrig”说起：一个把终端 AI 编码工具串起来的开源脚手架

第一次看到openrig这个名字，我下意识把它拆成了 “open” 和 “rig” 两半。rig 在英文里除了“装备、装置”，在工程语境里还有一层很实在的意思——把零散的部件搭成一个能干活的工作台。放到当下的开发场景里，这个理解几乎就是它的全部定位：把 Claude Code、Codex 这类终端里的 AI 编码助手，和 Node.js、tmux 这些底层运行时、会话管理工具，拼成一套开箱即用的本地开发环境。

如果你最近在折腾 Claude Code 或者 Codex，大概率踩过这些坑：Node.js 版本对不上，装到一半报error installing 24.21.0: node.js v24.21.0 is not yet released or is not available；Codex 登录之后提示your organization has disabled claude subscription access；配置里多写了一个字段，终端甩给你一句codex is ignoring 1 unrecognized configuration setting. check for typos；想在 VS Code 里同时用 Claude Code 和 Codex，结果两边环境互相打架。openrig想解决的，就是这类“工具都对、就是拼不起来”的问题。

它适合谁？三类人最值得看：一是刚接触 Claude Code、Codex，连 Node.js 是干什么的都还没完全搞明白的新手；二是已经在用这些工具，但每次换机器、换系统都要重新配一遍环境的老手；三是想把本地模型（比如通过 LM Studio 跑的模型）接进 Claude Code、Codex，做一套完全离线或半离线工作流的人。下面我按自己实际搭环境的顺序，把 openrig 这套思路拆开讲透。

2. openrig 的整体设计思路：为什么是“脚手架”而不是“安装包”

2.1 它到底解决的是哪一类问题

很多人第一次接触 Claude Code 或 Codex，会以为它们是一个“下载即用”的桌面软件。实际上这两个东西本质上是命令行工具，依赖 Node.js 运行时，靠 npm 全局安装，运行在终端里，通过 API 或本地模型通信。这就决定了它们的安装从来不是“双击下一步”那么简单，而是一串有先后依赖的操作：先有 Node.js，再有 npm，再装 CLI，再配 API Key 或本地模型地址，最后还要处理终端会话、代理、环境变量。

openrig的价值就在于把这串操作固化下来。它不是一个官方安装器，而是一套约定好的目录结构、脚本和配置模板，让你在一台新机器上，用尽量少的命令把 Claude Code、Codex、Node.js、tmux 这几样东西组装成一个稳定可用的工作台。我把它理解成“给终端 AI 编码工具用的 dotfiles 加强版”——dotfiles 管的是你的 shell 配置，openrig 管的是你的 AI 编码工具链。

2.2 为什么选 Node.js 作为底座

Claude Code 和 Codex 的 CLI 都是 Node.js 生态的产物，这一点从热搜词里node.js安装、node.js官网下载、node.js lts下载的高频出现就能看出来。Node.js 在这里扮演的角色，类似于 Python 之于 pip 安装的工具——它是运行时，是包管理器 npm 的宿主。没有它，npm install -g这类命令根本无从谈起。

选 Node.js 还有一个现实原因：跨平台一致性。Windows、macOS、Ubuntu 上都能装 Node.js，装完之后 Claude Code、Codex 的安装命令基本一致。openrig 的思路就是抓住这个一致性，把平台差异收敛到“装 Node.js”这一步，后面的步骤尽量统一。这也是为什么热搜里ubuntu配置claude code、claude code windows、ubuntu 安装claude code会同时出现——大家都在不同系统上做同一件事。

2.3 为什么把 tmux 拉进来

tmux 出现在关键词里，一开始我有点意外，后来想通了。Claude Code 和 Codex 都是长时间运行的交互式进程，你不可能一直盯着一个终端窗口。tmux 提供的是会话持久化：你关掉终端窗口，会话还在后台跑；你重新连上来，接着之前的上下文继续。对于需要跑长任务、或者同时开多个 AI 编码会话的人来说，tmux 几乎是刚需。

openrig 把 tmux 纳入体系，本质上是把“AI 编码会话”当成一种需要被管理的长期资源。你可以开一个 tmux 窗口跑 Claude Code，另一个窗口跑 Codex，第三个窗口跑本地模型服务，互不干扰，随时切换。这个设计思路很务实，不是堆功能，而是解决真实的多任务场景。

2.4 方案选型背后的取舍

这里要说清楚一个取舍：openrig 没有选择做成一个“一键安装脚本”。原因很简单，一键脚本在不同系统、不同网络环境、不同 Node.js 版本下极其脆弱，一个环节失败就全盘卡住，而且报错信息往往被脚本吞掉，排查起来更痛苦。openrig 选择的是“分步可验证”的路线——每一步都能单独跑、单独看结果，出问题能定位到具体环节。

这个取舍对新手其实更友好。你装 Node.js 失败了，就知道问题在 Node.js；装 CLI 失败了，就知道问题在 npm 或网络。比起一个黑盒脚本跑完告诉你“安装失败”，分步方式的学习成本和排查成本都低得多。我个人非常认同这个设计，踩过一键脚本坑的人都懂。

3. 核心组件拆解与实操要点

3.1 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 版本，不要追最新的 Current 版本。LTS 是长期支持版，稳定性和生态兼容性都经过验证，Claude Code、Codex 这类工具在 LTS 上跑最稳。截至我写这篇内容时，Node.js 20.x 和 22.x 都是可靠的 LTS 选择。安装方式上，Windows 和 macOS 直接去 Node.js 官网下载 LTS 安装包，Ubuntu 可以用 NodeSource 的源或者 nvm。

# Ubuntu 上用 nvm 安装 Node.js LTS 的典型流程 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v npm -v

装完之后一定要跑node -v和npm -v验证。我见过太多人装完不验证，后面 CLI 装不上，回头查半天才发现是 Node.js 根本没装成功。这一步花十秒钟，能省半小时排查。

注意：Windows 上如果之前装过旧版 Node.js，建议先卸载干净再装新版，否则可能出现 PATH 里新旧版本混用，node -v显示的版本和你以为的不一样。

3.2 Claude Code 安装与配置的关键细节

Claude Code 的安装本身不复杂，npm install -g一条命令的事，但配置环节坑比较多。热搜里your organization has disabled claude subscription access for claude code这个报错，通常和账号权限或订阅状态有关，不是安装问题。遇到这个，先确认你的账号是否有对应权限，再检查是不是用错了登录方式。

另一个高频问题是note: claude code might not be available in your country。这类提示属于服务可用性层面的限制，不是技术故障，遇到时按官方文档说明的方式处理即可，不要去找所谓的“绕过方法”，那既不安全也不稳定。

配置层面，Claude Code 支持通过环境变量指定 API 端点和密钥。如果你要接本地模型，比如通过 LM Studio 跑起来的模型，就需要把端点指向本地地址。热搜里claude code 调用lmstudio的本地模型说的就是这个场景。典型做法是设置ANTHROPIC_BASE_URL之类的环境变量，指向 LM Studio 暴露的本地接口。

# 示例：把 Claude Code 指向本地模型服务（具体变量名以官方文档为准） export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="local-key"

这里的关键是 LM Studio 那边要先启动服务，并且确认它暴露的接口格式和 Claude Code 期望的格式兼容。很多人卡在这一步，是因为本地模型服务的接口协议和云端不一致，需要中间做一层适配。openrig 的思路是把这类适配配置模板化，换机器时直接套用。

3.3 Codex 安装：Windows 桌面版与 CLI 的差异

Codex 的安装有两个路径，一个是 CLI，一个是 Windows 桌面版。热搜里codex安装 windows桌面版、codex cli、codex安装包都指向这个分化。CLI 版和 Claude Code 类似，走 npm 全局安装；桌面版则是独立安装包，适合不习惯命令行的用户。

CLI 版安装后，配置主要在~/.codex/之类的目录下。热搜里codex is ignoring 1 unrecognized configuration setting. check for typos or d这个报错，就是配置文件里写了它不认识的字段。Codex 的配置字段是严格校验的，多一个少一个都会提示。遇到这个，最直接的办法是打开配置文件，对照官方文档逐个字段核对，把不认识的删掉或改对。

codex无法加载组织设置这个报错则偏向账号和组织层面，通常和登录状态、组织策略有关。排查顺序是：先确认登录成功，再确认账号所属组织没有限制，最后看配置文件里的组织相关字段是否正确。

3.4 tmux 会话管理：让 AI 编码任务跑得更久

tmux 的安装在各平台都很简单，Ubuntu 上apt install tmux，macOS 上brew install tmux。真正需要花心思的是会话组织方式。我的习惯是给每个长期任务开一个独立会话，命名清晰，比如claude-main、codex-test、local-model。

# 创建并进入一个名为 claude-main 的会话 tmux new -s claude-main # 列出所有会话 tmux ls # 重新连接到指定会话 tmux attach -t claude-main # 在会话内按 Ctrl+b 然后 d 可以脱离，会话继续在后台运行

这套操作看起来简单，但配合 Claude Code、Codex 使用时有奇效。你可以让 Claude Code 在一个会话里跑一个长任务，自己切到另一个会话干别的，任务不会因为终端关闭而中断。对于需要长时间推理或批量处理的任务，这个能力非常实用。

提示：tmux 默认的前缀键是Ctrl+b，如果你经常和 Claude Code 的快捷键冲突，可以在~/.tmux.conf里改成别的，比如Ctrl+a。

4. 完整实操流程：从零搭起一套 openrig 工作台

4.1 环境准备与依赖检查

正式动手前，先做一次依赖体检。这一步很多人跳过，结果后面出问题不知道从哪查。检查清单如下：操作系统版本、是否已装 Node.js 及版本、npm 是否可用、是否有 tmux、网络是否能访问 npm 源。

# 依赖体检命令 node -v npm -v tmux -V npm config get registry

如果node -v报 command not found，说明 Node.js 没装或没进 PATH。如果 npm 源指向了一个访问不了的地址，后面装 CLI 会一直超时。这几条命令跑一遍，心里就有底了。

4.2 分步安装与验证

我推荐的安装顺序是：Node.js → npm 源确认 → Claude Code → Codex → tmux 会话组织。每装完一个就验证一个，不要一口气全装完再一起测。

# 安装 Claude Code（具体包名以官方为准） npm install -g @anthropic-ai/claude-code # 安装 Codex（具体包名以官方为准） npm install -g @openai/codex # 验证安装 claude --version codex --version

验证通过后再进入配置环节。配置的核心是 API 端点、密钥、模型选择。如果你用云端服务，就填官方端点；如果用本地模型，就填本地地址。这一步的配置建议单独存成文件或环境变量脚本，方便迁移。

4.3 接入本地模型的参数计算与选择

接本地模型时，有几个参数需要想清楚。第一是模型规模，本地能跑多大的模型取决于你的显存或内存。第二是量化等级，量化越低精度损失越大但占用越小。第三是上下文长度，AI 编码任务往往需要长上下文，这个参数直接影响可用性。

举个实际的例子：如果你有 16GB 显存，跑一个 7B 到 14B 参数的模型比较现实，量化选 4bit 或 8bit。上下文长度设到 8K 到 32K 之间，具体看模型支持。这些参数在 LM Studio 里都能调，调完之后把服务地址填进 Claude Code 或 Codex 的配置。

注意：本地模型的接口协议不一定和云端完全一致，接入时可能需要一层适配。如果 Claude Code 或 Codex 报接口格式错误，先确认本地服务暴露的是不是兼容的 API 格式。

4.4 用 tmux 组织多任务工作流

环境搭好之后，用 tmux 把任务组织起来。我的典型布局是三个会话：一个跑 Claude Code 做主开发，一个跑 Codex 做辅助验证，一个跑本地模型服务。三个会话独立运行，随时切换。

# 启动本地模型服务会话 tmux new -s local-model # 在会话内启动 LM Studio 的服务或对应命令 # 另开一个会话跑 Claude Code tmux new -s claude-main claude # 再开一个跑 Codex tmux new -s codex-aux codex

这套布局的好处是资源隔离清晰，哪个环节出问题一目了然。本地模型服务挂了，只影响依赖它的会话；Claude Code 卡住了，切到 Codex 继续干活。对于重度使用 AI 编码工具的人来说，这种组织方式能显著提升效率。

5. 常见问题与排查技巧实录

5.1 安装类问题速查

这张表是我自己踩坑之后整理的，基本覆盖了安装阶段八成以上的报错。遇到报错先查表，能省不少时间。

5.2 配置类问题的排查思路

配置类问题比安装类更隐蔽，因为工具能启动，但行为不对。比如 Claude Code 能跑起来，但连不上模型；Codex 能登录，但加载不了组织设置。这类问题的排查核心是“分层定位”：先确认网络层通不通，再确认认证层过没过，最后确认配置层对不对。

网络层用curl测端点，认证层看登录状态和密钥，配置层逐字段核对。这个顺序不要乱，从底层往上查，能最快定位问题所在。我见过有人一上来就改配置，结果发现是网络根本不通，白折腾半天。

5.3 本地模型接入的独家避坑技巧

接本地模型有几个坑，官方文档一般不写。第一，本地服务的接口路径可能和云端不一样，比如云端是/v1/messages，本地可能是/v1/chat/completions，需要确认清楚。第二，本地模型的响应格式可能有细微差异，导致工具解析失败。第三，本地服务的并发能力有限，同时跑多个请求可能排队甚至超时。

我的做法是先用curl直接测本地服务，确认它能正常返回符合格式的响应，再把它接进 Claude Code 或 Codex。这样能把“本地服务本身的问题”和“工具接入的问题”分开，排查起来清晰得多。

# 测试本地模型服务是否正常响应 curl http://localhost:1234/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"local-model","messages":[{"role":"user","content":"hello"}]}'

如果这条命令能返回正常结果，说明本地服务没问题，问题在工具配置；如果返回错误，先修本地服务。

5.4 多工具共存的冲突处理

Claude Code 和 Codex 同时装在一台机器上，偶尔会有冲突，主要是环境变量和配置文件互相干扰。比如两个工具都读某个同名环境变量，但期望的值不一样。处理办法是给每个工具用独立的配置目录或独立的环境变量前缀，避免混用。

tmux 会话层面也要注意，不同会话里的环境变量是独立的，这其实是好事，可以给 Claude Code 会话和 Codex 会话设置不同的环境变量，互不影响。利用好这一点，多工具共存反而比单工具更灵活。

6. 我个人的一些实操体会

搭这套环境的过程中，我最大的体会是“慢就是快”。一开始我也想过找个一键脚本全自动搞定，结果脚本跑完一堆报错，排查起来比手动装还慢。后来改成手动分步，每步验证，虽然看起来步骤多，但整体时间反而更短，而且出了问题知道去哪查。

另一个体会是配置要版本化。把 Claude Code、Codex 的配置文件、环境变量脚本、tmux 配置都放进一个目录，用 git 管起来。换机器的时候直接 clone 下来，改改路径就能用。这个习惯让我在换电脑、重装系统时省了大量重复劳动，openrig 这套思路本质上也是这个理念的延伸。

最后分享一个小技巧：给 tmux 会话起名时带上日期或任务标识，比如claude-20250115-refactor，这样开了一堆会话之后还能一眼看出哪个是哪个。会话多了之后，命名规范比任何工具都管用。这套工作流后续还可以往自动化方向扩展，比如写个脚本一键拉起所有会话和对应工具，但那是下一步的事了，先把基础打牢更重要。