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 用户可以用 HomebrewLinux 用户根据发行版用对应的包管理器。但不管你用哪种方式装完之后一定要验证node -v和npm -v都要能正常输出版本号。如果node -v报“command not found”说明 PATH 没配好这时候去折腾 Claude Code 是白费力气。2.3 tmux 在整套方案里的角色tmux 出现在热词里不是偶然。Claude Code 这类工具经常需要长时间运行比如你让它执行一个复杂的重构任务它可能跑几分钟甚至更久。如果你直接在普通终端里跑一旦网络波动或者你不小心关了窗口任务就断了。tmux 解决的就是这个问题它让你在一个持久化的会话里运行命令即使你断开连接会话还在后台跑着。但 tmux 的学习曲线对新手不太友好。它的快捷键体系跟普通终端完全不一样默认前缀是Ctrlb所有操作都要先按前缀再按功能键。我见过不少人装了 tmux 之后不知道怎么退出卡在里面干着急。其实记住几个核心操作就够了Ctrlb然后d是断开detachtmux attach是重新连接Ctrlb然后c是新建窗口Ctrlb然后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 node20。注意这里指定了主版本号因为 Homebrew 默认可能装最新版而不是 LTS。装完之后可能需要手动 linkbrew link node20 --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:$PATHWindows 上一般不会有权限问题但如果你用的是 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 tmuxmacOS 上brew install tmux。装完之后直接在终端输入tmux就进入了一个新会话。我常用的工作流是这样的先创建一个命名会话tmux new -s claude然后在里面启动 Claude Code。这样即使我关掉终端窗口会话还在后台跑着。下次回来的时候tmux attach -t claude就能恢复。如果忘了会话名字tmux ls可以列出所有会话。tmux 里有个很实用的功能是窗口分割。Ctrlb然后%是垂直分割Ctrlb然后是水平分割。这样你可以一个窗口跑 Claude Code另一个窗口跑 Codex第三个窗口看日志。切换窗口用Ctrlb然后方向键。注意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/v1API 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-essentialbuild-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 和 Codexnpm 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 配置。然后Ctrlb再按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 模型接入的典型故障速查表故障现象可能原因排查方法解决方案请求超时后端地址不可达curl测试后端端点检查地址和端口确认服务已启动401 未授权API key 错误或缺失检查配置文件里的 key重新生成 key 并更新配置404 找不到端点端点路径写错对照后端文档确认路径修正 base URL 和端点路径模型无响应模型名称不匹配查看后端支持的模型列表改成后端实际加载的模型名上下文超限输入太长查看后端日志的 token 数减少输入或换长上下文模型代理转发失败格式不匹配开 debug 日志看转发详情配置格式转换或换代理工具这张表是我在实际使用中总结出来的大部分模型接入问题都能归到这几类里。遇到新问题的时候先对照这张表定位方向再去查具体日志。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里可以配一些顺手的快捷键比如把前缀改成Ctrla或者配置鼠标支持。这些配置在新机器上直接复制过去就行。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 就能用。这样能保证团队成员的开发环境一致减少“在我机器上能跑”的问题。我个人在实际操作中的体会是这套环境的价值不在于装了多少工具而在于你理解了多少环节。工具会更新配置会变化但只要你清楚每个组件在链路里的位置和作用遇到问题就能快速定位。最开始我也是一路报错一路查现在回头看那些踩过的坑反而成了最有用的经验。