openrig 环境编排：AI 编程助手本地部署与模型切换实战

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，我下意识以为是某个硬件外设或者开源机械臂项目，毕竟 rig 这个词在工程领域通常跟“装配、搭建、设备”挂钩。但翻了一圈社区讨论和实际用法之后才明白，openrig 在当前语境下，指的是一套围绕 AI 编程助手（Claude Code、Codex 这类 CLI 工具）搭建的本地开发环境编排方案。说白了，它解决的不是“怎么写代码”的问题，而是“怎么让这些 AI 编程工具在你机器上稳定跑起来、互相配合、还能随时切换模型后端”的问题。

这个定位其实非常关键。现在用 Claude Code 或者 Codex 的人越来越多，但大部分人卡住的地方根本不是模型能力不够，而是环境本身太折腾：Node.js 版本不对、终端复用器没配好、代理转发失败、组织权限被禁用、配置文件里一个拼写错误就导致整个 CLI 罢工。openrig 要做的，就是把这些零散的配置动作收敛成一套可复现的“装备流程”，让你换一台机器、换一个系统，都能快速把整套工具链拉起来。

适合看这篇内容的人有三类。第一类是刚接触 Claude Code 或 Codex、连安装都没跑通的新手，你需要一份不绕弯子的落地路径。第二类是已经在用但经常被各种报错打断的开发者，你需要知道那些错误背后到底发生了什么。第三类是想把 AI 编程工具接入本地模型或第三方 API 的人，你需要理解整个链路里哪些环节可以替换、哪些不能动。我会尽量把每一步的“为什么”讲清楚，而不是只丢一堆命令让你抄。

2. 整体设计思路：为什么要把环境“装备化”

2.1 从“装一个工具”到“编排一套环境”的思维转变

早几年装开发工具，思路很简单：下载、安装、配个 PATH，完事。但 Claude Code 和 Codex 这类工具完全不是这个逻辑。它们本质上是 CLI 程序，依赖 Node.js 运行时，需要终端环境支持交互式会话，还要通过网络访问模型服务，中间任何一环出问题，表现出来都是“命令跑了但没反应”或者“报一个看不懂的错”。

我踩过的第一个坑就是 Node.js 版本。当时系统里装的是某个非 LTS 版本，Claude Code 安装脚本直接报error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错看起来像是网络问题，实际上是版本号根本不存在，安装器去拉一个不存在的版本自然失败。如果你不理解 Node.js 的版本发布节奏，就会在这个错误上耗很久。

openrig 这套思路的核心，就是把“工具”当成“环境”来对待。它不假设你的机器是干净的，也不假设你只用一个工具。它要处理的是：多个 AI 编程助手共存、多个模型后端切换、多个终端会话管理。这就引出了几个关键设计决策。

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

Claude Code 和 Codex 的 CLI 都是 Node.js 生态的产物，这不是偶然。Node.js 的包管理体系和跨平台能力，让这些工具可以用一套代码同时支持 Windows、macOS 和 Linux。但代价是，你必须有一个健康的 Node.js 环境。

这里有个很多人忽略的点：Node.js 的 LTS 版本和非 LTS 版本差别很大。LTS 版本经过长时间测试，稳定性和兼容性都有保障；非 LTS 版本虽然版本号更高，但可能引入破坏性变更。我个人的建议是，永远用 LTS 版本，哪怕它看起来“旧”。你可以去 Node.js 官网下载页面确认当前 LTS 是哪个版本，不要凭记忆或者随便搜一个版本号就装。

安装方式上，Windows 用户直接下安装包最省事，macOS 用户可以用 Homebrew，Linux 用户根据发行版用对应的包管理器。但不管你用哪种方式，装完之后一定要验证：node -v和npm -v都要能正常输出版本号。如果node -v报“command not found”，说明 PATH 没配好，这时候去折腾 Claude Code 是白费力气。

2.3 tmux 在整套方案里的角色

tmux 出现在热词里不是偶然。Claude Code 这类工具经常需要长时间运行，比如你让它执行一个复杂的重构任务，它可能跑几分钟甚至更久。如果你直接在普通终端里跑，一旦网络波动或者你不小心关了窗口，任务就断了。tmux 解决的就是这个问题：它让你在一个持久化的会话里运行命令，即使你断开连接，会话还在后台跑着。

但 tmux 的学习曲线对新手不太友好。它的快捷键体系跟普通终端完全不一样，默认前缀是Ctrl+b，所有操作都要先按前缀再按功能键。我见过不少人装了 tmux 之后不知道怎么退出，卡在里面干着急。其实记住几个核心操作就够了：Ctrl+b然后d是断开（detach），tmux attach是重新连接，Ctrl+b然后c是新建窗口，Ctrl+b然后n是切换窗口。这几个够你日常用了。

在 openrig 的语境下，tmux 的价值在于它让 AI 编程工具的运行状态和你的终端连接解耦。你可以在 tmux 里启动 Claude Code，然后断开去干别的事，回来再 attach 上去看进度。这对于需要长时间等待的任务来说，体验提升非常明显。

2.4 模型后端的可替换性设计

热词里出现了cc switch、deepseek、qwen、glm、lmstudio这些词，说明很多人不满足于只用官方模型服务，而是想接入本地模型或者第三方 API。这个需求很合理：本地模型没有网络延迟，第三方 API 可能更便宜，而且不同模型在不同任务上表现不一样。

openrig 的思路是把模型后端当成一个可替换的组件。Claude Code 和 Codex 本身支持配置不同的 API 端点，你只需要改配置文件里的 base URL 和 API key，就能把请求转发到不同的后端。但这里有个常见的坑：cc switch local proxy failed while handling codex endpoint /responses这个报错，通常是因为代理配置和实际端点不匹配。Codex 用的是/responses端点，如果你配的代理只处理/v1/chat/completions，那请求就会失败。

所以配置模型后端的时候，一定要确认三件事：端点路径对不对、API key 有没有权限、模型名称跟后端支持的是否一致。这三件事任何一件出问题，都会表现为“请求失败”或者“模型无响应”。

3. 核心细节解析与实操要点

3.1 Node.js 安装：版本选择与验证

Node.js 的安装看起来简单，但细节很多。先说版本选择。截至我写这篇内容的时候，Node.js 的 LTS 版本是 20.x 系列，但具体小版本号会随时间变化。你去 Node.js 官网下载页面，会看到两个推荐版本：LTS 和 Current。选 LTS，不要选 Current。

Windows 用户下载.msi安装包，双击一路下一步就行。但有一个选项要注意：安装过程中会问你要不要自动安装必要的工具，比如 Python 和 Visual Studio Build Tools。如果你以后要编译原生模块，这个选项要勾上；如果只是跑 CLI 工具，不勾也行，能省不少安装时间。

macOS 用户如果用 Homebrew，命令是brew install node@20。注意这里指定了主版本号，因为 Homebrew 默认可能装最新版而不是 LTS。装完之后可能需要手动 link：brew link node@20 --force。Linux 用户用apt或者dnf的时候，系统仓库里的 Node.js 版本往往比较旧，建议用 NodeSource 的仓库来装，能拿到比较新的 LTS 版本。

装完之后的验证步骤不能省。打开一个新的终端窗口，依次执行：

node -v npm -v npx -v

三个命令都要能正常输出版本号。如果node -v有输出但npm -v报错，说明 npm 没装好或者 PATH 有问题。这种情况在 Windows 上比较常见，因为安装器有时候不会自动把 npm 加到 PATH 里。解决办法是手动把 Node.js 安装目录加到系统环境变量里，然后重启终端。

提示：如果你之前装过其他版本的 Node.js，建议先卸载干净再装新版本。多个版本共存会导致 PATH 混乱，表现出来就是“明明装了新版本但node -v显示的还是旧版本”。

3.2 Claude Code 安装与首次配置

Claude Code 的安装方式取决于你的系统。官方推荐的方式是通过 npm 全局安装：

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

但这里有个前提：你的 npm 全局安装目录要有写权限。Linux 和 macOS 上，如果之前用sudo装过东西，npm 的全局目录可能归 root 所有，普通用户装不了。解决办法是配置 npm 的全局目录到用户目录下：

npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH

Windows 上一般不会有权限问题，但如果你用的是 PowerShell，可能需要以管理员身份运行才能全局安装。

装完之后，第一次运行claude命令会引导你登录。如果你所在地区不支持官方服务，可能会看到note: claude code might not be available in your country这样的提示。这种情况下你需要配置第三方 API 或者本地模型，具体方法在下一节讲。

还有一个常见报错是your organization has disabled claude subscription access for claude code。这个跟你的账号类型有关，如果你用的是企业账号，管理员可能关闭了 Claude Code 的访问权限。解决办法是换个人账号，或者联系管理员开通。

3.3 Codex 安装与配置要点

Codex 的安装跟 Claude Code 类似，也是 npm 全局安装。但 Codex 的配置项更多，也更容易出错。热词里有个报错很典型：codex is ignoring 1 unrecognized configuration setting. check for typos or d。这个报错的意思是，你的配置文件里有一个 Codex 不认识的配置项，它选择忽略但提醒你检查拼写。

Codex 的配置文件通常放在用户目录下的.codex文件夹里，文件名可能是config.json或者config.toml。具体格式取决于版本，建议装完之后先跑一次codex --help看看它期望的配置格式。配置项里比较关键的有：API 端点、API key、默认模型、超时时间。如果你接的是第三方 API，端点路径一定要跟后端匹配，前面提到的/responses端点问题就是这里出的。

另一个常见问题是codex无法加载组织设置。这个通常是因为你的账号没有加入任何组织，或者组织设置拉取失败。如果你只是个人使用，可以忽略这个错误，它不影响基本功能。但如果它导致 Codex 完全无法启动，那就需要检查网络连接和账号状态。

3.4 tmux 会话管理与实操技巧

tmux 的安装很简单，Ubuntu 上sudo apt install tmux，macOS 上brew install tmux。装完之后直接在终端输入tmux就进入了一个新会话。

我常用的工作流是这样的：先创建一个命名会话tmux new -s claude，然后在里面启动 Claude Code。这样即使我关掉终端窗口，会话还在后台跑着。下次回来的时候，tmux attach -t claude就能恢复。如果忘了会话名字，tmux ls可以列出所有会话。

tmux 里有个很实用的功能是窗口分割。Ctrl+b然后%是垂直分割，Ctrl+b然后"是水平分割。这样你可以一个窗口跑 Claude Code，另一个窗口跑 Codex，第三个窗口看日志。切换窗口用Ctrl+b然后方向键。

注意：tmux 里的复制粘贴跟系统剪贴板默认是不通的。如果你需要把 tmux 里的内容复制到系统剪贴板，macOS 上可以按住 Option 键用鼠标选择，Linux 上需要额外配置。这个坑我踩过好几次，一开始以为复制成功了，结果粘贴出来是空的。

3.5 模型后端切换的配置方法

把 Claude Code 或 Codex 接到本地模型或者第三方 API，核心就是改配置。以接入本地 LM Studio 为例，LM Studio 默认在本地的 1234 端口提供 OpenAI 兼容的 API。你需要在 Claude Code 的配置里把 base URL 改成http://localhost:1234/v1，API key 随便填一个非空字符串（本地服务通常不验证），模型名称填你在 LM Studio 里加载的模型名。

但这里有个细节：Claude Code 和 Codex 对 API 格式的要求可能不一样。Claude Code 用的是 Anthropic 自己的消息格式，而 LM Studio 提供的是 OpenAI 兼容格式。如果你直接把 Claude Code 指向 LM Studio，可能会因为格式不匹配而失败。解决办法是用一个转换层，比如 cc switch 这类工具，它能把 Anthropic 格式的请求转成 OpenAI 格式再转发给本地模型。

cc switch 的配置里有一个关键项是端点路径。如果你接的是 Codex，端点要写成/responses；如果接的是 Claude Code，端点可能是/v1/messages。这个路径写错了，就会看到cc switch local proxy failed while handling codex endpoint /responses这样的报错。我的经验是，先把 cc switch 的日志级别调到 debug，然后发一个测试请求，看它实际转发到了哪个路径，再对照后端的文档确认路径是否正确。

4. 实操过程与核心环节实现

4.1 从零搭建一套可用的 openrig 环境

假设你拿到一台全新的 Ubuntu 机器，想把这套环境搭起来。我会按顺序走一遍，每一步都说明为什么这么做。

第一步，更新系统包列表并安装基础工具：

sudo apt update sudo apt install -y curl git tmux build-essential

build-essential是为了后面可能编译原生模块用的，现在装上省得后面再折腾。curl用来下载安装脚本，git用来拉取一些配置仓库，tmux前面说过了。

第二步，安装 Node.js LTS。用 NodeSource 的脚本：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs

装完验证node -v和npm -v。如果版本号显示的是 20.x，说明装对了。

第三步，配置 npm 全局目录到用户目录，避免权限问题：

mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

第四步，安装 Claude Code 和 Codex：

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

如果这两个包名有变化，以官方文档为准。装完之后which claude和which codex应该能输出路径。

第五步，创建 tmux 会话并启动工具：

tmux new -s ai-tools claude

在 Claude Code 里完成登录或者 API 配置。然后Ctrl+b再按d断开，回到普通终端。下次用tmux attach -t ai-tools恢复。

这套流程走下来，你就有了一套基本可用的环境。但实际使用中还会遇到各种问题，下一节专门讲排查。

4.2 接入本地模型的完整配置示例

假设你想让 Claude Code 用本地 LM Studio 的模型，而不是官方服务。LM Studio 里先加载一个模型，比如 Qwen 或者 DeepSeek 的量化版本，然后在 LM Studio 的开发者面板里启动本地服务器，默认端口 1234。

接下来配置 cc switch。cc switch 的配置文件通常在~/.cc-switch/config.json，内容大概长这样：

{ "providers": { "local-lmstudio": { "baseUrl": "http://localhost:1234/v1", "apiKey": "lm-studio", "models": { "default": "qwen2.5-7b-instruct" } } } }

然后在 Claude Code 的配置里把 API 端点指向 cc switch 的本地代理地址。cc switch 默认监听一个本地端口，比如 3456，那么 Claude Code 的 base URL 就填http://localhost:3456。

这里的关键是 cc switch 要正确识别请求格式并转发。如果 Claude Code 发的是 Anthropic 格式，cc switch 要把它转成 OpenAI 格式再发给 LM Studio。这个转换过程如果出错，就会看到前面提到的代理失败报错。排查方法是看 cc switch 的日志，确认它收到了什么格式的请求、转发到了什么地址、后端返回了什么。

提示：本地模型的上下文长度通常比官方模型短，如果你让 Claude Code 处理一个很大的代码库，可能会因为超出上下文而失败。解决办法是在 Claude Code 里限制它读取的文件范围，或者换一个上下文更长的本地模型。

4.3 VS Code 集成配置

很多人习惯在 VS Code 里用 Claude Code，而不是在终端里。VS Code 有 Claude Code 的扩展，装完之后可以在编辑器里直接调用。但扩展本质上还是调用底层的 CLI，所以 CLI 的配置必须先弄好。

VS Code 里配置 Claude Code 的关键是确保扩展能找到 CLI 的可执行文件。如果claude命令在终端里能用，但 VS Code 扩展报“找不到命令”，通常是因为 VS Code 的环境变量跟终端不一样。解决办法是在 VS Code 的设置里手动指定 Claude Code 的路径，或者把 npm 全局目录加到 VS Code 继承的环境变量里。

Windows 上这个问题更常见，因为 VS Code 可能用的是 PowerShell 的环境，而你在 CMD 里配的 PATH 不一定对 PowerShell 生效。我的做法是统一在系统环境变量里配，然后重启 VS Code。

4.4 多工具共存的目录结构规划

当你同时用 Claude Code、Codex 和其他 AI 编程工具时，配置文件散落在各处会很难管理。我建议在用户目录下建一个统一的配置目录，比如~/.ai-tools/，然后把各个工具的配置软链接过去。这样备份和迁移的时候只需要处理一个目录。

具体来说，Claude Code 的配置可能在~/.claude/，Codex 的在~/.codex/，cc switch 的在~/.cc-switch/。你可以把这些目录都移到~/.ai-tools/下面，然后在原位置创建符号链接：

mv ~/.claude ~/.ai-tools/claude ln -s ~/.ai-tools/claude ~/.claude

这样工具本身感觉不到变化，但你的配置集中了。换机器的时候，把~/.ai-tools/打包带走就行。

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

5.1 安装阶段的高频报错与解决

安装阶段最常见的问题就是 Node.js 版本不对。前面提到的error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是一个典型。这个报错的意思是安装器试图去下载一个不存在的 Node.js 版本。为什么会这样？因为某些工具的安装脚本里硬编码了一个版本号，而这个版本号可能还没发布，或者已经下架了。

解决办法是手动指定一个存在的 LTS 版本。如果你是用 nvm 管理 Node.js 版本，可以nvm install 20然后nvm use 20。如果你是用系统包管理器，确保仓库里的版本是 LTS。

另一个常见问题是网络超时。npm 安装包的时候如果卡住不动，可能是默认的 npm 源访问不畅。可以换成国内镜像源：

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

换完之后再装，速度会快很多。但要注意，有些包可能没有同步到镜像源，如果装的时候报 404，换回官方源再试。

5.2 运行阶段的配置错误排查

运行阶段的问题通常跟配置有关。codex is ignoring 1 unrecognized configuration setting这个报错说明配置文件里有一个 Codex 不认识的键。Codex 通常会告诉你它忽略了哪个键，你根据提示找到那一行，要么删掉，要么改成正确的键名。

cc switch local proxy failed while handling codex endpoint /responses这个报错说明代理在处理 Codex 的/responses端点时失败了。可能的原因有三个：代理没有正确配置/responses路径的处理逻辑、后端不支持这个端点、请求格式不匹配。排查顺序是：先确认代理配置里有没有/responses的路由，再确认后端是否支持这个端点，最后看请求格式。

your organization has disabled claude subscription access for claude code这个报错跟配置无关，是账号权限问题。如果你用的是企业账号，需要管理员在后台开通 Claude Code 的访问权限。个人账号一般不会遇到这个问题。

5.3 模型接入的典型故障速查表

这张表是我在实际使用中总结出来的，大部分模型接入问题都能归到这几类里。遇到新问题的时候，先对照这张表定位方向，再去查具体日志。

5.4 我踩过的几个坑和独家建议

第一个坑是 tmux 里的环境变量。我在 tmux 会话里启动 Claude Code，结果它找不到 API key，因为我在.bashrc里配的环境变量在 tmux 会话里没生效。原因是 tmux 启动的时候可能没有加载.bashrc。解决办法是在 tmux 里手动source ~/.bashrc，或者把环境变量配到.profile里。

第二个坑是 npm 全局安装的包在 tmux 里找不到。这是因为 tmux 的 PATH 可能跟登录 shell 不一样。解决办法是在.bashrc里确保 PATH 包含 npm 全局目录，并且 tmux 启动时加载.bashrc。

第三个坑是本地模型的并发限制。有些本地模型服务默认只允许一个并发请求，如果你同时跑 Claude Code 和 Codex，第二个请求会排队或者直接失败。解决办法是在本地模型服务里调大并发数，或者错开使用时间。

提示：如果你在 Windows 上用 WSL 跑这套环境，注意 WSL 的文件系统性能跟原生 Linux 有差异。把项目文件放在 WSL 的文件系统里（比如/home/username/projects），不要放在/mnt/c/下面，否则文件读写会慢很多，AI 工具扫描代码库的时候会明显卡顿。

6. 环境迁移与日常维护

6.1 把环境从一台机器搬到另一台

当你在一台机器上把 openrig 环境调好之后，肯定不想在另一台机器上从头再来一遍。我的做法是维护一个安装脚本，把关键步骤写成可执行的命令。脚本里包括：安装 Node.js、配置 npm 全局目录、安装 Claude Code 和 Codex、创建配置目录的软链接。

配置文件本身用 git 管理，但要注意 API key 不能提交到仓库里。我的做法是配置文件里用环境变量占位，实际的 key 放在一个不提交的.env文件里。迁移的时候，把.env文件单独拷贝过去。

tmux 的配置也可以迁移。~/.tmux.conf里可以配一些顺手的快捷键，比如把前缀改成Ctrl+a，或者配置鼠标支持。这些配置在新机器上直接复制过去就行。

6.2 日常维护的几个习惯

第一个习惯是定期更新 Node.js 和工具版本。Node.js 的 LTS 版本每隔一段时间会有小版本更新，修复安全漏洞和 bug。Claude Code 和 Codex 也会不定期发布新版本。更新之前先看 changelog，确认没有破坏性变更再升。

第二个习惯是保留一份可用的配置备份。每次改配置之前，先把当前可用的配置复制一份。这样改坏了可以快速回滚。我一般会在配置目录里建一个backup文件夹，按日期存备份。

第三个习惯是关注日志。Claude Code 和 Codex 在运行的时候会输出日志，遇到问题的时候日志是第一手信息。可以把日志级别调到 debug，这样能看到更详细的请求和响应内容。但 debug 日志量很大，问题解决之后记得调回来。

6.3 后续可以扩展的方向

这套环境搭好之后，还可以往几个方向扩展。一个是加监控，比如用htop或者glances看本地模型的资源占用，避免模型把内存吃满导致系统卡死。另一个是加自动化，比如写一个脚本，一键启动 tmux 会话、启动本地模型服务、启动 Claude Code，省去手动操作的麻烦。

还有一个方向是多人共享。如果你在团队里推广这套工具，可以把配置模板化，每个人只需要填自己的 API key 就能用。这样能保证团队成员的开发环境一致，减少“在我机器上能跑”的问题。

我个人在实际操作中的体会是，这套环境的价值不在于装了多少工具，而在于你理解了多少环节。工具会更新，配置会变化，但只要你清楚每个组件在链路里的位置和作用，遇到问题就能快速定位。最开始我也是一路报错一路查，现在回头看，那些踩过的坑反而成了最有用的经验。