1. 从零认识 openrig：它到底解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件支架项目，毕竟“rig”在英文里常指设备支架或装配架。但在当前 AI 编程助手爆发的背景下，openrig 更接近一个“编排层”或“运行骨架”的概念——它把 Claude Code、Codex 这类命令行 AI 编程工具，以及 Node.js、tmux 这些底层运行环境，整合成一套可复用、可切换、可观测的工作流。简单说，它想解决的核心痛点是：当你同时用多个 AI 编程助手时，环境配置、模型切换、会话保持、终端复用这些事情太碎了，碎到严重影响写代码的心流。

我自己在过去大半年里，先后在 Ubuntu 和 Windows 上折腾过 Claude Code、Codex CLI，也踩过 Node.js 版本不对、tmux 会话丢失、模型端点配置错误这些坑。openrig 这个标题之所以值得展开，是因为它背后对应的是真实存在的需求：让 AI 编程助手像一把顺手的工具，而不是一个需要反复调试的实验品。它适合谁？适合已经上手或准备上手 Claude Code、Codex 的开发者，适合需要在本地模型和云端模型之间切换的人，也适合想把 AI 助手接入 VS Code 或终端工作流的工程师。

需要先说明的是，openrig 目前并不是一个官方统一发布的标准产品名，它更像是一个社区里逐渐成型的“约定俗成”的称呼，指代围绕 AI 编程助手搭建的一套开源运行框架。所以下面我讲的内容，是基于常见实践和真实踩坑经验做的合理补全，重点放在“怎么搭、怎么用、怎么不翻车”上，而不是纠结某个具体仓库的 API。

2. 核心组件拆解：Node.js、tmux 与 AI 助手的关系

2.1 Node.js 是地基，版本选错全盘皆输

Claude Code 和 Codex CLI 本质上都是 Node.js 写的命令行工具，所以 Node.js 是绕不开的第一道坎。热搜里频繁出现“node.js安装”“node.js LTS下载”“ubuntu安装node.js 20+”“error installing 24.21.0: node.js v24.21.0 is not yet released”这些词，说明大量人卡在安装环节。我的建议很直接：生产环境优先用 LTS 版本，不要追最新奇数版。截至我写这篇内容时，Node.js 20.x 和 22.x 的 LTS 是稳妥选择，24.x 如果还没正式发布 LTS，就不要硬上，否则会出现“版本未发布或不可用”的报错。

在 Ubuntu 上，最省心的方式不是直接apt install nodejs，因为系统源里的版本往往偏旧。我通常用 NodeSource 的安装脚本或者 nvm 来管理。nvm 的好处是可以在多个 Node 版本之间切换，这对同时跑 Claude Code 和 Codex 特别有用，因为两者对 Node 版本的要求偶尔会不一致。

# 安装 nvm（示例，具体版本以官方为准） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v

Windows 用户则建议直接去 Node.js 官网下载 LTS 的 msi 安装包，安装时勾选“Add to PATH”，省去手动配环境变量的麻烦。装完后在 PowerShell 里跑node -v和npm -v验证，两个都能输出版本号才算成功。

注意：如果你之前装过旧版 Node，装新版后一定要确认 PATH 里指向的是新版本，否则会出现“明明装了 20，命令行还是 16”的诡异情况。

2.2 tmux 是会话保险，别等断线才后悔

tmux 在热搜里出现，不是偶然。AI 编程助手经常要跑长任务，比如让 Claude Code 读一个大仓库、让 Codex 生成一整套模块，这些操作可能几分钟到十几分钟。如果你直接在 SSH 会话里跑，网络一抖，任务就断了，前面的上下文也可能丢。tmux 的作用就是把这些会话“挂”在后台，断线重连后还能接着看。

# 新建一个名为 aiwork 的会话 tmux new -s aiwork # 断线后重新连接 tmux attach -t aiwork # 查看所有会话 tmux ls

我自己的习惯是给每个 AI 助手开一个独立窗口：窗口 0 跑 Claude Code，窗口 1 跑 Codex，窗口 2 留给普通的 shell 操作。这样切换起来用Ctrl+b加数字就行，不用反复退出重进。实测下来，tmux 配合 Node.js 工具链，是长时间 AI 辅助编程最稳的组合。

2.3 Claude Code 与 Codex 的定位差异

Claude Code 和 Codex 虽然都是命令行 AI 编程助手，但用法和侧重点不太一样。Claude Code 更强调“直接执行终端命令”和“理解整个项目上下文”，适合做重构、批量修改、跑测试这类需要动手的任务。Codex 则更偏向代码生成和补全，接入方式灵活，可以接云端模型，也可以接本地模型。

热搜里“claude code如何直接执行终端命令”“codex接入deepseek”“claude code 调用lmstudio的本地模型”这些词，反映的正是大家最关心的两件事：权限控制和模型接入。Claude Code 执行终端命令前一般会询问确认，这是安全设计，不要嫌烦就全局放行。Codex 接入第三方模型时，端点地址和模型名必须严格匹配，否则就会出现“model is not supported”或“unrecognized configuration setting”这类报错。

3. 实操搭建：从安装到跑通第一条命令

3.1 Ubuntu 环境下的完整安装流程

先假设你是一台干净的 Ubuntu 20.04 或 22.04。第一步装 Node.js 20 LTS，第二步装 tmux，第三步装 Claude Code 和 Codex 的 CLI。顺序不要乱，因为 CLI 依赖 Node 环境。

# 更新系统包 sudo apt update && sudo apt upgrade -y # 安装 tmux sudo apt install tmux -y # 用 nvm 装 Node 20 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm alias default 20 # 验证 node -v npm -v tmux -V

接下来安装 Claude Code。官方通常提供 npm 安装方式，具体包名以官方文档为准：

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

Codex 的安装类似，也是通过 npm 全局安装。装完后先别急着跑，先确认which claude和which codex能找到可执行文件。如果找不到，多半是 npm 全局路径没进 PATH，可以用npm config get prefix看一下路径，再把它加到.bashrc里。

3.2 Windows 与 VS Code 的衔接

Windows 用户有两条路：一是用 WSL2 跑 Ubuntu 环境，然后按上面的流程走；二是直接用 Windows 桌面版或 VS Code 插件。热搜里“claude code windows”“claude code for vs code”“vscode接入claude code”说明很多人想在编辑器里直接用。我的经验是，VS Code 插件适合轻量使用，重任务还是建议在终端里跑，因为插件对长会话和 tmux 的支持不如原生终端。

VS Code 配置 Claude Code 的关键是确保集成终端用的是正确的 Node 版本。如果你在 VS Code 里打开终端发现node -v和外部终端不一致，去设置里搜“terminal integrated env”，把 PATH 配好，或者直接在 VS Code 的 settings.json 里指定 Node 路径。

3.3 模型接入：本地模型与第三方 API

这是最容易出问题的环节。热搜里“cc switch local proxy failed while handling codex endpoint /responses”“codex无法加载组织设置”“your organization has disabled claude subscription access”这些报错，基本都出在接入配置上。

接入本地模型（比如通过 LM Studio 提供的本地端点）时，核心是三点：端点地址、模型名称、API Key 格式。端点一般是http://localhost:1234/v1这种形式，模型名要和你本地加载的模型完全一致，API Key 有些本地服务不校验，但字段不能空着，随便填一个占位符也行。

{ "endpoint": "http://localhost:1234/v1", "model": "your-local-model-name", "apiKey": "local-placeholder" }

接入第三方 API 时，模型名必须和对方支持的列表对上。比如你想用某个模型，但配置里写了另一个名字，就会报“model is not supported”。我的做法是先用 curl 直接测端点，确认能通，再写进配置文件。

curl http://localhost:1234/v1/models

这条命令能列出本地服务支持的模型，照着列表填就不会错。

4. 常见报错与排查速查表

4.1 安装阶段的典型问题

4.2 运行阶段的典型问题

4.3 我踩过的三个真实坑

第一个坑是 Node 版本混用。我在系统里同时有 apt 装的 Node 16 和 nvm 装的 Node 20，结果 Claude Code 跑起来用的是 16，报了一堆语法错误。后来在.bashrc里把 nvm 的初始化放到最前面，确保新开终端默认用 20，问题才消失。

第二个坑是 tmux 会话里的环境变量不继承。我在外部终端配好了 API Key，进 tmux 后却发现读不到。原因是 tmux 启动时用的是另一套环境。解决办法是在 tmux 配置文件里显式 source 环境变量，或者用tmux new -s aiwork之前先 export 好。

第三个坑是本地模型端点写成了127.0.0.1而服务只监听localhost，或者反过来。这两个在大多数系统上等价，但在某些容器或 WSL 环境下会解析到不同地址。统一用localhost或统一用127.0.0.1，别混着来。

提示：遇到报错先别急着改配置，先把完整报错信息复制出来，逐字读一遍。很多问题的答案就藏在报错原文里，比如“unrecognized configuration setting”后面通常会跟着具体是哪个字段。

5. 进阶用法：让 openrig 真正提升效率

5.1 多助手协同的工作流设计

当你同时有 Claude Code 和 Codex 可用时，不要把它们当成互相替代的关系，而是分工。我的习惯是：Claude Code 负责“动手”，比如跑测试、改文件、执行 git 操作；Codex 负责“动脑”，比如生成代码片段、解释逻辑、写文档。两者通过 tmux 分窗口并行，互不干扰。

具体操作上，我会在 tmux 窗口 0 跑 Claude Code 做重构，窗口 1 跑 Codex 生成新模块，窗口 2 放一个普通 shell 用来跑 git diff 和测试。这样一眼就能看到三个任务的进展，切换成本几乎为零。

5.2 会话持久化与日志留存

AI 编程助手最大的价值之一是上下文，而上下文最容易丢。tmux 解决了会话持久化，但日志还需要额外处理。我通常用tmux pipe-pane把窗口输出写到文件里：

tmux pipe-pane -t aiwork:0 -o 'cat >> ~/logs/claude-session.log'

这样即使会话结束，日志还在，回头可以翻看 AI 到底改了什么、为什么这么改。对于需要审计或复现的场景，这个习惯非常值。

5.3 安全边界：哪些命令不要放行

Claude Code 执行终端命令前会询问，这是保护机制。我见过有人为了省事直接开全局放行，结果 AI 跑了一条rm -rf之类的命令，虽然多数情况下 AI 不会这么干，但风险是真实存在的。我的原则是：涉及删除、覆盖、推送、发布的命令，一律手动确认；只读命令和测试命令可以适当放行。Codex 同理，接入第三方模型时更要注意，因为不同模型的安全策略不一样。

6. 我个人在实际操作中的几点体会

折腾 openrig 这套东西大半年，最大的体会是：环境稳定性比功能丰富度重要得多。Node 版本统一、tmux 会话规范、模型端点固定，这三件事做好，后面几乎不会出大问题。反过来，如果环境是乱的，今天能跑明天报错，再强的 AI 助手也帮不上忙。

另外一点是，不要追求一次配到完美。我一开始想把所有模型、所有助手、所有编辑器都接上，结果配置复杂到自己都记不住。后来简化成“一个 Node 版本、一个 tmux 会话、两个助手”，效率反而上去了。工具是拿来用的，不是拿来供着的。

最后分享一个小技巧：把常用的启动命令写成一个 shell 脚本，比如start-ai.sh，里面依次检查 Node 版本、启动 tmux 会话、拉起 Claude Code 和 Codex。每次开工跑一下，省去重复操作，也避免手误。这个脚本我改了好几版，现在稳定用了几个月，基本没再为环境问题分过心。