1. openrig 到底想解决什么问题

第一次看到openrig这个名字，我下意识把它拆成了 “open” + “rig” 两个部分。rig 在工程语境里通常指“装配好的成套设备”或者“工作台”，放到软件领域，它更像是一套把零散工具组装起来、让它们协同工作的脚手架。结合热词里高频出现的 Claude Code、Codex、Node.js、tmux 这几个关键词，我基本能判断出 openrig 的定位：它大概率是一个面向终端 AI 编程助手的工作环境编排工具，目标是把 Claude Code、Codex 这类命令行 AI 工具，和 Node.js 运行时、tmux 会话管理整合成一套开箱即用的“装备架”。

为什么我会有这个判断？因为热词列表里几乎全是围绕“安装、配置、接入、报错”展开的：claude code安装、codex安装教程、node.js安装、ubuntu配置claude code、vscode配置claude code、codex接入deepseek、cc switch local proxy failed……这些词说明大量用户卡在了“把工具跑起来”这一步，而不是卡在“用工具写出好代码”这一步。openrig 要做的，就是把这堆琐碎的安装、环境变量、代理转发、会话保持问题一次性收拢。

我自己的经历很能说明问题。早些年我在一台 Ubuntu 机器上同时装 Claude Code 和 Codex，光是 Node.js 版本就折腾了两个小时——系统自带的 Node 太老，nvm 装的版本又和某个全局包冲突，最后发现是node.js v24.21.0 is not yet released这种版本号写错导致的。这类问题不是技术难题，但极其消耗耐心。openrig 这类工具的价值，就在于把“环境准备”从一件需要查十篇教程的事，变成一条命令或者一份配置文件。

这篇文章适合三类人看：第一类是刚接触终端 AI 编程助手、被安装步骤劝退的新手；第二类是已经在用 Claude Code 或 Codex、但想把它接入本地模型或第三方 API 的进阶用户；第三类是想在团队里统一开发环境、避免“我这能跑你那不能跑”的工程负责人。我会从 openrig 的核心机制讲起，把 Node.js、tmux、Claude Code、Codex 这几块拼图逐一拆开，再给出可复现的配置步骤和踩坑记录。

提示：本文提到的所有工具和配置，均以官方文档和公开技术资料为准，涉及具体版本号时请以你实际环境为准，不要照抄我文中的版本数字。

2. openrig 的核心机制：它凭什么把工具“架”起来

2.1 从“手动拼装”到“声明式编排”的转变

传统做法是这样的：你先装 Node.js，再npm install -g装 Claude Code，然后手动配环境变量，再开一个 tmux 窗口跑 Codex，接着发现 Codex 要连本地模型还得改配置文件，改完发现端口冲突，又去查cc switch local proxy failed while handling codex endpoint /responses这个报错到底什么意思。整个过程是命令式的——你一步步告诉机器该做什么，任何一步出错都得回头重来。

openrig 的思路是声明式的：你在一份配置文件里描述“我要什么”，比如“我要一个 Node.js 20 的环境、一个跑 Claude Code 的 tmux 会话、一个把 Codex 指向本地 LM Studio 的代理”，然后 openrig 负责把实际状态调整到和你的描述一致。这个思路和 Docker Compose、Terraform 是一脉相承的，只不过编排的对象从容器、云资源变成了终端 AI 工具。

我实测下来，声明式编排最大的好处不是省了几条命令，而是可复现。你在自己机器上跑通的配置，原样发给同事，他大概率也能跑通。手动装环境则完全靠运气，系统版本、已有全局包、shell 配置稍有不同就翻车。

2.2 Node.js 在 openrig 里的角色：不只是运行时

热词里node.js是干什么的、node.js安装、node.js lts下载出现频率极高，说明很多人对 Node.js 的定位是模糊的。在 openrig 的语境里，Node.js 扮演两个角色。

第一个角色是运行时宿主。Claude Code 和 Codex 的 CLI 版本本质上都是 Node.js 程序，它们依赖 Node 的模块系统和事件循环。没有 Node，这些工具根本启动不了。这也是为什么安装claude code和安装node.js总是成对出现。

第二个角色是版本敏感型依赖。Node.js 的版本迭代很快，LTS 和 Current 两条线并行。Claude Code 可能要求 Node 18 以上，Codex 可能对 Node 20 的某个特性有依赖，而你的系统包管理器里装的是 Node 16。这种版本错配是error installing 24.21.0: node.js v24.21.0 is not yet released这类报错的根源——你试图安装一个根本不存在的版本。

openrig 处理这个问题的常见做法是：在配置文件里锁定 Node 版本，然后用版本管理器（nvm、fnm 或 volta）在项目目录下切换。这样不同项目可以用不同 Node 版本，互不干扰。我个人的习惯是用 fnm，因为它启动快、跨平台一致性好，Windows 下配合 WSL 也很顺。

2.3 tmux：被低估的“会话保命符”

tmux出现在热词里，很多人可能觉得奇怪——一个终端复用器，和 AI 编程助手有什么关系？关系大了。

Claude Code 和 Codex 都是长时间运行的任务。你让它重构一个模块，它可能要跑几分钟甚至十几分钟。如果你直接在 SSH 会话里跑，网络一抖，会话断开，任务就没了。tmux 的作用就是把这些任务放进一个持久化的会话里，断线重连后任务还在跑。

更关键的是，openrig 这类工具通常需要同时管理多个进程：一个 Claude Code 实例、一个 Codex 实例、一个本地模型服务、一个代理转发。如果全挤在一个终端窗口里，输出会乱成一锅粥。tmux 的分窗和会话隔离能力，让每个进程有自己独立的“房间”，互不干扰，又能通过脚本统一控制。

我踩过的一个坑是：在 tmux 里跑 Claude Code，结果它检测到非交互式终端，行为变得很奇怪。后来发现是 tmux 的default-terminal设置不对，改成screen-256color或tmux-256color就正常了。这种细节，官方文档通常不会写，但实际用起来能卡你半天。

2.4 Claude Code 与 Codex 的差异化定位

热词里这两个名字几乎并驾齐驱，但它们的定位其实有差异。Claude Code 更偏向“对话式编程助手”，你描述需求，它生成代码、执行命令、解释结果，交互性强。Codex 更偏向“代码补全与生成引擎”，在编辑器里的集成度更高，适合边写边补全的场景。

openrig 要同时支持这两者，就必须处理它们的配置差异。比如 Claude Code 可能通过环境变量读取 API 密钥，Codex 可能通过配置文件读取；Claude Code 的代理设置可能走HTTPS_PROXY，Codex 可能走自己的endpoint配置。cc switch local proxy failed while handling codex endpoint /responses这个报错，就是代理配置和 Codex 的 endpoint 期望不匹配导致的。

理解这些差异，是配好 openrig 的前提。你不能指望一套配置原样套用到两个工具上，得分别对待。

3. 环境准备：Node.js 版本选择与安装的实战细节

3.1 为什么我不推荐用系统包管理器装 Node.js

Ubuntu 的apt install nodejs、macOS 的brew install node，看起来很方便，但我强烈不建议在 openrig 场景下这么做。原因有三个。

第一，系统包管理器里的 Node 版本通常滞后。Ubuntu 22.04 默认源里的 Node 可能是 12 或 14，而 Claude Code 和 Codex 往往要求 18 以上。你装完发现版本不够，还得卸载重装，反而更麻烦。

第二，系统级安装的 Node 权限管理混乱。全局包装在/usr/lib/node_modules，普通用户没权限，得加sudo。而sudo npm install -g又会带来一系列权限问题，最后你可能得去改/usr/local的属主，越搞越乱。

第三，多版本共存困难。你系统里只有一个 Node，项目 A 要 18，项目 B 要 20，你只能来回卸载重装。版本管理器则允许你同时装多个版本，按目录切换。

所以我的建议是：永远用版本管理器装 Node.js。nvm 是最老牌的选择，fnm 是后起之秀，volta 更偏向团队协作场景。三者选其一即可，我下面以 fnm 为例，因为它的安装脚本干净、启动速度快。

3.2 fnm 安装与 Node 版本锁定

在 Linux 或 macOS 下，fnm 的安装通常是一行脚本：

curl -fsSL https://fnm.vercel.app/install | bash

装完后需要把 fnm 的初始化脚本加到 shell 配置里。如果你用 bash，就在~/.bashrc末尾加：

eval "$(fnm env --use-on-cd)"

--use-on-cd这个参数很关键，它让你进入一个包含.node-version或.nvmrc文件的目录时，自动切换到对应 Node 版本。openrig 的配置文件里通常会指定 Node 版本，配合这个参数就能实现“进目录即切换”。

然后安装你需要的 Node 版本：

fnm install 20 fnm use 20 node -v

如果node -v输出的版本号和你预期不符，先检查which node指向的是不是 fnm 管理的路径。常见问题是 shell 配置里 fnm 的初始化顺序不对，被系统自带的 Node 抢先了。

注意：热词里出现的error installing 24.21.0: node.js v24.21.0 is not yet released这类报错，通常是因为版本号写错了。Node.js 的主版本号目前远没到 24，写配置时务必去官网确认当前 LTS 版本号，不要凭记忆填。

3.3 Windows 下的特殊处理

热词里claude code windows、codex安装 windows桌面版说明 Windows 用户不少。Windows 下装 Node.js 有两条路：直接装 Windows 版，或者用 WSL。

我的建议是用 WSL。原因很简单：Claude Code 和 Codex 的很多脚本、tmux、代理配置都是为 Unix 环境设计的，在 Windows 原生环境下经常遇到路径分隔符、权限、终端兼容性问题。WSL 给你一个完整的 Linux 环境，省去大量适配工作。

WSL 里装 fnm 和上面步骤一样。唯一要注意的是 WSL 的文件系统性能——把项目放在 WSL 自己的文件系统里（/home/yourname/），不要放在/mnt/c/下，否则文件读写会慢很多，Node 的node_modules安装会卡到你怀疑人生。

如果你坚持用 Windows 原生环境，那 Node.js 官网下载安装包是最稳妥的，装完后用 PowerShell 验证node -v和npm -v。但 tmux 在 Windows 原生环境下没有官方支持，你得用 WSL 或者第三方替代方案，这又绕回来了。

4. tmux 会话编排：让 AI 助手在后台稳定干活

4.1 为什么 openrig 离不开 tmux

前面提过 tmux 的会话保持能力，这里展开说。openrig 编排的进程通常有三类：AI 助手进程（Claude Code、Codex）、模型服务进程（本地 LM Studio、Ollama 等）、代理转发进程。这三类进程的生命周期不同，AI 助手可能跑几分钟就结束，模型服务要一直开着，代理转发要等所有请求处理完才能关。

如果不用 tmux，你得开三个终端窗口，手动管理每个进程的启停。一旦某个进程崩溃，你得去翻日志找原因。tmux 把这些进程放进命名会话里，你可以用脚本统一创建、查询、销毁，还能把输出重定向到日志文件。

更重要的是，tmux 支持“分离-重连”。你启动一个会话，跑上任务，然后Ctrl+b d分离，去干别的事。过一小时回来tmux attach，任务还在跑，输出还在。这种体验对于长时间运行的 AI 任务来说是刚需。

4.2 用脚本创建标准化的 tmux 会话

手动敲 tmux 命令容易出错，openrig 的常见做法是用脚本封装。下面是一个我常用的会话创建脚本，你可以根据自己的工具组合调整：

#!/bin/bash SESSION="openrig" # 如果会话已存在，先杀掉重建 tmux has-session -t $SESSION 2>/dev/null && tmux kill-session -t $SESSION # 创建新会话，第一个窗口跑模型服务 tmux new-session -d -s $SESSION -n "model" tmux send-keys -t $SESSION:model "cd ~/models && ./start-server.sh" C-m # 第二个窗口跑 Claude Code tmux new-window -t $SESSION -n "claude" tmux send-keys -t $SESSION:claude "cd ~/projects/myapp && claude" C-m # 第三个窗口跑 Codex tmux new-window -t $SESSION -n "codex" tmux send-keys -t $SESSION:codex "cd ~/projects/myapp && codex" C-m # 第四个窗口留给日志查看 tmux new-window -t $SESSION -n "logs" tmux send-keys -t $SESSION:logs "tail -f ~/logs/openrig.log" C-m echo "会话 $SESSION 已创建，用 tmux attach -t $SESSION 进入"

这个脚本的关键点在于send-keys的C-m参数，它模拟回车键，让命令真正执行。很多人写脚本时忘了这个，结果命令只是被“输入”到窗口里，没有执行。

4.3 tmux 配置里必须改的几个参数

默认的 tmux 配置有几个地方会让 AI 工具“水土不服”，我建议在~/.tmux.conf里加上这几行：

# 终端类型，影响颜色和交互检测 set -g default-terminal "tmux-256color" # 增大回滚缓冲区，AI 输出很长，默认 2000 行不够用 set -g history-limit 50000 # 鼠标支持，方便滚动查看输出 set -g mouse on # 窗口编号从 1 开始，符合直觉 set -g base-index 1 setw -g pane-base-index 1

history-limit这个参数特别重要。Claude Code 生成代码时输出量很大，默认缓冲区很快就被冲掉了，你想往上翻看之前的输出都翻不到。调到 50000 行后，基本能覆盖一次完整任务的输出。

default-terminal设置不对会导致颜色显示异常，甚至让某些工具误判终端能力。tmux-256color是目前兼容性最好的选择。

4.4 会话命名与日志落盘

openrig 管理多个项目时，会话命名要有规律。我的习惯是openrig-<项目名>，比如openrig-myapp、openrig-api。这样tmux ls一眼就能看出哪些会话属于哪个项目。

日志落盘是另一个容易被忽略的点。tmux 窗口里的输出默认只在内存里，会话一关就没了。如果你需要事后排查问题，得用pipe-pane把输出重定向到文件：

tmux pipe-pane -t $SESSION:claude -o 'cat >> ~/logs/claude-$(date +%Y%m%d).log'

这条命令把 claude 窗口的所有输出追加到日志文件里。-o参数表示只在新输出到达时触发，避免重复写入。排查cc switch local proxy failed这类报错时，日志文件比翻终端历史靠谱得多。

5. Claude Code 与 Codex 的接入配置：从报错反推正确姿势

5.1 Claude Code 安装后的第一件事：验证环境

装完 Claude Code 后，别急着写代码，先跑一遍环境检查。热词里claude code如何直接执行终端命令、claude code使用教程说明很多人装完不知道怎么用。我的建议是先用一个最小任务验证链路：让 Claude Code 执行echo hello这样的命令，看它能不能正确调用终端。

如果这一步就失败，问题通常出在权限或 shell 配置上。Claude Code 需要调用你的默认 shell 来执行命令，如果你的 shell 配置里有报错（比如某个source的文件不存在），Claude Code 的命令执行就会静默失败。检查方法是手动跑一遍bash -l -c "echo hello"，看有没有报错输出。

另一个常见问题是your organization has disabled claude subscription access for claude code这类提示。这通常和账号权限或订阅状态有关，不是本地配置能解决的。遇到这种提示，先确认你的账号状态，再检查是否用错了 API 端点。

5.2 Codex 接入本地模型的配置逻辑

热词里claude code 调用lmstudio的本地模型、codex接入deepseek说明本地模型接入是刚需。Codex 接入本地模型的核心是改 endpoint 配置，把默认的云端地址换成http://localhost:端口/v1。

以 LM Studio 为例，它默认在1234端口提供 OpenAI 兼容接口。Codex 的配置文件里需要指定：

# ~/.codex/config.toml model = "local-model" model_provider = "lmstudio" [model_providers.lmstudio] name = "LM Studio" base_url = "http://localhost:1234/v1" api_key = "not-needed"

api_key填not-needed是因为本地模型通常不校验密钥，但 Codex 的配置结构要求这个字段存在。如果你漏了，可能会遇到codex is ignoring 1 unrecognized configuration setting这类警告。

配置改完后，用codex --config-check或类似命令验证配置是否被正确加载。不同版本的 Codex 验证命令可能不同，以你安装的版本为准。

5.3 代理转发报错的排查链路

cc switch local proxy failed while handling codex endpoint /responses这个报错，我实际遇到过。排查过程大致如下。

第一步，确认代理进程是否在跑。ps aux | grep proxy看有没有相关进程。如果没有，说明代理根本没启动，问题在启动脚本。

第二步，确认端口是否被占用。lsof -i :端口号看谁在监听。如果被别的进程占了，代理启动会失败，但报错信息可能被吞掉。

第三步，确认 endpoint 路径是否匹配。Codex 期望的路径是/responses，如果你的代理配置里写的是/v1/responses或/chat/completions，就会 404。这个路径差异是很多代理工具的通病，配置时一定要对照 Codex 的文档。

第四步，看代理日志。如果代理有独立日志文件，里面通常会有更详细的错误信息，比如“upstream connection refused”或“invalid request format”。这些信息比终端上的报错有用得多。

我踩过的一个坑是：代理配置里写了localhost，但 Codex 在容器或 WSL 里跑，localhost指向的不是宿主机。改成宿主机的实际 IP 或host.docker.internal才通。这种网络命名空间的问题，不看日志根本想不到。

5.4 VS Code 集成：让 AI 助手住进编辑器

热词里vscode配置claude code、vscode接入claude code、claude code for vs code出现多次，说明编辑器集成是高频需求。VS Code 集成的好处是你不用在终端和编辑器之间来回切换，AI 生成的代码可以直接插入到当前文件。

配置的关键是让 VS Code 的终端使用和 openrig 一致的环境。如果你用 fnm 管理 Node，VS Code 的集成终端默认可能不加载 fnm 的初始化脚本，导致claude命令找不到。解决方法是在 VS Code 的settings.json里指定终端 profile：

{ "terminal.integrated.profiles.linux": { "bash": { "path": "bash", "args": ["-l"] } }, "terminal.integrated.defaultProfile.linux": "bash" }

-l参数让 bash 以登录 shell 方式启动，这样~/.bashrc里的 fnm 初始化才会执行。不加这个参数，VS Code 终端里的 PATH 可能和你在系统终端里看到的不一样。

6. 多工具共存时的冲突处理与经验总结

6.1 端口冲突：最隐蔽的“拦路虎”

openrig 同时跑多个服务时，端口冲突是最常见的问题。LM Studio 默认 1234，Ollama 默认 11434，代理工具可能默认 8080，Claude Code 和 Codex 各自可能还有内部端口。这些端口一旦撞车，报错信息往往指向别处，让你误以为是配置问题。

我的做法是维护一张端口分配表，写进 openrig 的配置文件里，启动前先检查端口占用。下面是一个简单的检查脚本：

#!/bin/bash PORTS=(1234 11434 8080 3000) for port in "${PORTS[@]}"; do if lsof -i :$port >/dev/null 2>&1; then echo "端口 $port 已被占用：" lsof -i :$port else echo "端口 $port 空闲" fi done

启动 openrig 前跑一遍，心里有数。如果某个端口被占，要么改配置换端口，要么找到占用进程决定是否杀掉。

6.2 环境变量污染：全局配置的陷阱

Claude Code 和 Codex 都读环境变量，比如ANTHROPIC_API_KEY、OPENAI_API_KEY、HTTPS_PROXY等。如果你在~/.bashrc里全局设置了这些变量，所有项目都会受影响。某天你换了个 API 提供商，忘了改全局变量，结果所有项目都报认证失败。

我的建议是把环境变量放在项目级的.env文件里，用 direnv 或类似工具在进入目录时自动加载。这样不同项目可以用不同的密钥和端点，互不干扰。direnv 的配置很简单，在~/.bashrc里加eval "$(direnv hook bash)"，然后在项目目录下创建.envrc文件写环境变量，direnv allow一下就行。

6.3 版本升级后的“回旋镖”

Node.js、Claude Code、Codex 都在快速迭代，升级后配置格式可能变化。我遇到过 Codex 升级后配置文件字段改名，旧配置被忽略，工具用默认端点跑，结果请求发到了错误的地方。codex is ignoring 1 unrecognized configuration setting这个警告就是信号——它在告诉你“你写的某个配置我不认识了”。

升级后第一件事是跑一遍配置验证，看有没有 unrecognized setting 的警告。有的话去官方文档查新字段名，别硬扛。第二件事是跑一个最小任务，确认端到端链路通。这两步花不了五分钟，但能避免你在真正干活时才发现问题。

6.4 我的 openrig 日常使用流程

最后分享一下我现在的日常流程，供你参考。

早上到工位，先跑openrig up（我自己封装的脚本），它会检查端口、启动 tmux 会话、拉起模型服务和代理。然后tmux attach -t openrig进去，在 claude 窗口开始一天的工作。遇到需要查资料的任务，切到 codex 窗口让它生成代码片段。模型服务的日志在 model 窗口，代理日志在 logs 窗口，有问题随时切过去看。

下班前跑openrig down，它会优雅关闭所有进程、把日志归档、清理临时文件。第二天openrig up又是干净的环境。这套流程跑顺之后，我花在环境维护上的时间从每天半小时降到了几乎为零。

这套东西的核心不是某个工具多厉害，而是把不确定性收拢到配置文件里。环境是声明式的，行为是可复现的，出问题有日志可查。openrig 这个名字里的 “rig”，我觉得精髓就在这——它不是某个单点工具，而是一整套让你能稳定干活的装备架。