1. 从 openrig 这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“成套装置”或者“把一堆零件组装成能跑起来的东西”比如矿机叫 mining rig测试台叫 test rig。所以openrig给我的第一直觉是一个开放的、把若干工具拼装成一套可用工作环境的装置或脚手架。结合热搜词里高频出现的 Claude Code、Codex、Node.js、tmux 这几个关键词我基本能判断出 openrig 的定位——它大概率是一个围绕 AI 编程助手Claude Code、Codex CLI 这类终端智能体搭建的本地运行环境或编排工具。它要解决的问题很具体这些 AI 编程工具本身是命令行程序依赖 Node.js 运行时长时间跑任务需要会话保持tmux多模型切换需要代理层而把这些东西从零装好、配好、串起来对很多人来说是一道不低的门槛。我自己在这类工具上折腾过不少时间最深的体会是装一个工具只要十分钟但让它稳定地、可复用地跑起来往往要花掉一整个下午。问题不在于某个工具难而在于它们之间的衔接——Node 版本不对、PATH 没配好、终端一关进程就死、模型端点填错、组织权限被禁用每一个都能让你卡住。openrig 这类项目的价值就是把这些零散的“胶水工作”固化下来变成一套可复制、可迁移的装置。这篇文章我不打算写成一份干巴巴的安装手册而是想从一个实际使用者的角度把 openrig 背后涉及的几个核心环节拆开讲透Node.js 运行时为什么是地基、tmux 为什么是长任务的命脉、Claude Code 和 Codex 这类 CLI 智能体的配置逻辑是什么、多模型接入时那些报错到底在说什么。如果你正在搭自己的 AI 编程工作台或者被cc switch local proxy failed这类报错折磨过这篇应该能帮你少走点弯路。2. Node.js 运行时所有 CLI 智能体的地基也是最容易翻车的地方2.1 为什么这些工具都绑在 Node.js 上Claude Code、Codex CLI 这类工具本质上是用 JavaScript/TypeScript 写的命令行程序通过 npm 分发。它们要跑起来机器上必须有一个 Node.js 运行时。这就好比你要运行一个 Python 脚本得先有 Python 解释器一样没什么玄学。但 Node.js 有个让新手很头疼的特点版本迭代快而且不同工具对版本的要求不一致。热搜词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型的版本问题——你照着某个教程敲了一个版本号结果那个版本根本不存在或者还没发布npm 直接报错。这种情况十有八九是教程写的时候版本存在等你看到的时候已经被新的版本号取代了。我的建议很直接不要手动去记版本号用 LTS长期支持版。Node.js 官网会把当前 LTS 版本放在最显眼的位置这个版本经过充分测试兼容性最好。你搜node.js lts下载或者node.js官网下载认准 LTS 标识就行。截至我写这篇的时候Node 20.x 和 22.x 都是稳定的 LTS 线选哪个都不会有大问题。2.2 安装 Node.js 的三种路径以及我为什么推荐版本管理器装 Node.js 大致有三条路我按推荐程度从低到高排一下安装方式适用场景优点坑点官网安装包纯新手、只装一次图形化下一步下一步全局只有一个版本升级麻烦系统包管理器Linux 用户一条命令搞定版本往往偏旧权限问题多版本管理器nvm/fnm需要多版本切换随时切换互不干扰初次配置略麻烦我强烈推荐第三条路。原因很简单你不可能只用一个 Node 版本。今天 Claude Code 要求 Node 18明天某个工具可能对 Node 22 有更好的支持后天你又要跑一个老项目需要 Node 16。如果全局只有一个版本每次切换都要卸载重装那简直是灾难。用 nvmNode Version Manager的话流程是这样的# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 或 ~/.zshrc # 安装并使用某个 LTS 版本 nvm install --lts nvm use --lts # 验证 node -v npm -vWindows 用户可以用 nvm-windows逻辑一样只是安装包是 exe。装完之后nvm install 20装 20.xnvm use 20切过去干净利落。提示装完 nvm 之后一定要重开一个终端窗口或者手动 source 一下配置文件否则nvm命令会提示找不到。这个坑我踩过不止一次明明装好了却用不了就是因为当前 shell 还没加载新的环境变量。2.3 npm 全局安装的权限陷阱Node 装好之后下一步通常是用 npm 全局安装 CLI 工具比如npm install -g anthropic-ai/claude-code或者 Codex 对应的包。这里有个高频坑权限报错。在 macOS/Linux 上如果你用系统自带的 Node通过 apt 或官网 pkg 装的全局安装目录往往在/usr/local/lib/node_modules普通用户没写权限于是 npm 报EACCES错误。很多教程会让你加sudo我劝你别这么干——用 sudo 装全局包后续升级、卸载都会遇到权限混乱而且有安全风险。正确的做法有两个一是用 nvm 管理 Node全局包会装在你的用户目录下天然没权限问题二是如果非要用系统 Node就重新配置 npm 的全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加到 PATH export PATH~/.npm-global/bin:$PATH把上面这行 export 写进~/.bashrc或~/.zshrc以后就一劳永逸了。这个细节看起来小但它决定了你后面装 Claude Code、Codex 时是顺风顺水还是步步报错。3. tmux让 AI 编程任务在后台活下去的关键3.1 为什么关掉终端任务就死了这是很多人第一次用 CLI 智能体时的困惑我让 Claude Code 帮我重构一个模块它正在跑我手贱把终端窗口关了回来一看任务没了。原因在于终端里跑的进程是会话的子进程。你关掉终端等于杀死了这个会话所有挂在它下面的进程都会被一起带走。这跟你在图形界面里关掉一个程序它里面的子任务全停是一个道理。AI 编程任务有个特点耗时长。它可能要读几十个文件、跑几轮推理、执行若干终端命令整个过程几分钟到几十分钟不等。你不可能一直盯着终端不动更不可能保证网络不断、电脑不锁屏。这时候就需要一个“会话保持”工具让进程脱离当前终端独立存活。tmux 就是干这个的。它创建一个持久的会话你的进程跑在会话里终端只是“连上去看”的一个窗口。你断开连接会话还在你重新连上看到的还是原来的画面。热搜词里 tmux 和 Claude Code 一起出现不是偶然这是长任务场景下的刚需组合。3.2 tmux 的最小可用操作集tmux 的命令不少但日常真正高频的就那么几个。我把它压缩成一张表操作命令说明新建会话tmux new -s work创建一个叫 work 的会话断开后台运行Ctrlb然后d进程继续跑你回到普通终端查看会话列表tmux ls列出所有会话重新连接tmux attach -t work回到 work 会话杀死会话tmux kill-session -t work彻底结束Ctrlb是 tmux 的默认前缀键所有快捷键都要先按它。这个设计一开始会不习惯但用几次就形成肌肉记忆了。典型的工作流是这样的# 开一个会话专门跑 AI 任务 tmux new -s claude # 在会话里启动 Claude Code claude # 给它一个长任务然后按 Ctrlb 再按 d 断开 # 去干别的事过半小时回来 tmux attach -t claude3.3 在 tmux 里跑 AI 任务的两个实战心得第一个心得给会话起有意义的名字。我见过有人开了一堆tmux new不带名字的会话最后tmux ls出来一排0: 1 windows、1: 1 windows根本分不清哪个是哪个。养成-s起名的习惯比如-s codex-refactor、-s claude-test回头找起来一目了然。第二个心得注意 tmux 里的滚动和复制。tmux 会接管鼠标滚动默认情况下你滚轮往上翻翻的是 tmux 的缓冲区不是终端的历史。要进入复制模式得按Ctrlb然后[用方向键或 PageUp/PageDown 翻页按q退出。这个如果不熟悉会以为“终端卡住了”。另外AI 任务输出的日志往往很长tmux 默认的滚动缓冲区是 2000 行跑长任务可能不够可以在~/.tmux.conf里加一行set-option -g history-limit 50000把缓冲区调大。注意如果你在 tmux 里跑的任务需要交互输入比如 Claude Code 问你“是否继续”断开再连回来之后界面可能不会自动刷新。这时候按一下回车或者CtrlL刷新一下屏幕通常就能看到最新状态。4. Claude Code 与 Codex 的配置逻辑报错信息其实是路标4.1 这两个工具在配置上有什么共性Claude Code 和 Codex CLI 虽然出自不同团队但配置逻辑高度相似都是“认证 模型端点 本地设置”这三件事。认证解决的是“你是谁”模型端点解决的是“请求发到哪”本地设置解决的是“行为怎么调”。三者任何一个出问题工具都跑不起来。热搜词里那一大堆报错几乎都能归到这三类里。先看认证类。your organization has disabled claude subscription access for claude code这条说的是你的组织管理员关闭了 Claude Code 的订阅访问权限。这不是你本地配置的问题而是账号层面的策略限制。遇到这种个人用户基本无解只能换账号或者联系管理员企业用户则要找 IT 确认策略。再看note: claude code might not be available in your country. check supported co...这类提示属于区域可用性检查。工具在启动时会检测你所在的区域是否在支持列表里不在就给出提示。这类信息是工具自身的合规检查看到之后按提示确认支持范围即可。4.2 模型端点配置本地模型与第三方 API 的接入热搜词里有一条很典型claude code 调用 lmstudio 的本地模型。这说明很多人不满足于用官方模型想把请求指向本地跑的模型比如通过 LM Studio 加载的开源模型或者指向第三方 API 服务。这个需求本身很合理——本地模型免费、数据不出机器、可以离线用。但配置起来有几个关键点第一端点地址要写全。本地服务通常跑在http://localhost:1234/v1这样的地址上很多人只填了localhost:1234少了/v1路径请求就 404。这个/v1是 OpenAI 兼容接口的约定路径别漏。第二模型名称要对得上。本地加载的模型有个标识名配置里填的名字必须和 LM Studio 里显示的一致否则服务端找不到模型返回错误。第三API Key 不能空着。有些本地服务不校验 Key但客户端可能要求这个字段非空。随便填一个字符串比如sk-local通常就能过。配置大致长这样以环境变量方式为例export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYsk-local export ANTHROPIC_MODELyour-local-model-nameCodex 接入第三方服务的逻辑类似也是通过 base URL 和 key 指向目标端点。热搜词里的codex接入deepseek就是这个套路——把 Codex 的请求指向 DeepSeek 的兼容接口。4.3 那条 cc switch local proxy failed 报错到底在说什么cc switch local proxy failed while handling codex endpoint /responses这条报错信息量很大值得单独拆一下。cc switch大概率是一个用于切换 Claude Code 配置或模型来源的辅助工具社区里这类切换脚本很多。local proxy说明它在本地起了一个代理层用来转发请求。failed while handling codex endpoint /responses说明代理在处理发往/responses这个端点的请求时失败了。/responses是 Codex 类工具使用的接口路径。代理失败的可能原因有几个代理进程没起来或者端口被占用目标端点的地址配错了代理转发到了一个不存在的地址请求格式和目标端点不兼容比如把 Anthropic 格式的请求发给了 OpenAI 格式的端点认证信息在代理转发过程中丢失了排查顺序我建议这样先确认代理进程在不在ps aux | grep proxy或看端口lsof -i :端口号再确认目标端点能不能直接访问用 curl 打一下最后看请求格式对不对。代理层的报错八成是“转发目标”或“格式转换”的问题而不是代理本身坏了。4.4 配置文件的那些“小脾气”热搜词里还有两条很有意思codex is ignoring 1 unrecognized configuration setting. check for typos or d...和codex无法加载组织设置。第一条说的是配置文件里有个字段它不认识被忽略了。这通常是拼写错误或者用了旧版本的字段名。工具会明确告诉你“ignoring 1 unrecognized setting”你只要去配置文件里找到那个字段对照官方文档确认正确拼写就行。别小看这个警告有时候一个拼错的字段会导致整个配置块失效。第二条“无法加载组织设置”多半是账号权限或网络问题。组织级设置需要从服务端拉取如果认证 token 过期、网络不通、或者账号不在组织里就会加载失败。先检查登录状态再检查网络最后确认账号归属。提示改完配置文件后很多工具需要重启才生效。别改完就急着测先退出再重进省得怀疑人生。5. 编辑器集成VS Code 里用 Claude Code 的正确姿势5.1 为什么要在编辑器里用而不是纯终端纯终端用 Claude Code 完全没问题但如果你本来就在 VS Code 里写代码把 AI 助手集成进来会顺手很多。好处很直接不用在编辑器和终端之间来回切AI 改的文件能直接在编辑器里看到 diff确认无误再保存。热搜词里vscode配置claude code、claude code for vs code、vscode接入claude code反复出现说明这是很多人的实际需求。VS Code 的集成方式通常有两种一是装官方或社区的扩展二是在 VS Code 的集成终端里直接跑 CLI。5.2 集成终端方式的实操细节我个人更推荐第二种——在 VS Code 的集成终端里跑 CLI。原因是不依赖扩展的更新节奏CLI 有什么新功能你立刻就能用上。操作上要注意几点第一VS Code 集成终端默认用的是系统 shell你之前配的 PATH、nvm 环境变量要确保在这个 shell 里也生效。如果终端里node -v报找不到命令说明 VS Code 启动时没加载你的 shell 配置。macOS 上可以在 VS Code 设置里把默认终端改成zsh或bash并确认terminal.integrated.inheritEnv是开启的。第二在集成终端里同样可以用 tmux。这样即使你关掉 VS Code任务还在后台跑。这一点很多人不知道以为 VS Code 关了终端就没了。第三注意工作目录。CLI 工具通常以当前目录为工作区你在 VS Code 里打开的项目根目录最好就是终端的工作目录否则 AI 可能读不到你的项目文件。5.3 扩展方式的取舍如果你选择装扩展要注意扩展和 CLI 可能是两套独立的配置。有时候你在 CLI 里配好了模型端点扩展却读的是另一份配置导致行为不一致。遇到这种情况去扩展的设置里找对应的配置项手动对齐。另外扩展的更新可能滞后于 CLI。CLI 出了新模型支持扩展可能还没跟上。这也是我偏向 CLI 的原因之一——离源头越近越不容易被中间层坑。6. 把 openrig 当成一套可复用的工作台来搭6.1 从零到可用的完整顺序把前面几块拼起来一套基于 openrig 思路的工作台搭建顺序应该是这样的装 Node.js 版本管理器nvm/fnm用它装一个 LTS 版本配置 npm 全局目录避免权限问题装 tmuxLinux 用包管理器macOS 用 brew全局安装 Claude Code / Codex CLI配置认证和模型端点官方或本地/第三方在 tmux 会话里启动任务断开后让它后台跑按需集成到 VS Code这个顺序不能乱。Node 是地基tmux 是保障CLI 是主体配置是灵魂编辑器集成是锦上添花。跳过任何一步后面都会以某种报错的形式找上门。6.2 一套可迁移的配置清单我习惯把关键配置集中管理换机器的时候直接搬。清单大致是~/.bashrc或~/.zshrc里的 PATH 和 nvm 初始化~/.tmux.conf里的 history-limit 等设置CLI 工具的配置文件通常在~/.config/或~/.claude/之类的目录下环境变量文件模型端点、API Key 等把这些用 git 管理起来注意别把密钥提交上去换机器时 clone 下来改改路径就能用。这套东西的价值不在于省那点安装时间而在于保证环境一致性——你在这台机器上跑通的东西换台机器不会因为某个隐藏配置缺失而崩掉。6.3 几个我反复踩过的坑最后分享几个实打实的教训。坑一Node 版本和工具要求不匹配。症状是安装时报 engine 不兼容或者运行时报奇怪的语法错误。解决方法是看工具的package.json里engines字段的要求用 nvm 切到对应版本。坑二tmux 里环境变量丢失。有时候你在普通终端里配好的环境变量进 tmux 会话就没了。这是因为 tmux 启动时可能没加载你的 shell 配置。解决办法是在~/.tmux.conf里加set-option -g update-environment PATH ANTHROPIC_API_KEY ...把需要的变量显式传进去。坑三代理层和直连混用导致混乱。如果你既配了本地代理又设了直连端点请求可能走错路。同一时间只保留一套配置要切换就整体切别让两套配置打架。坑四以为报错是工具坏了其实是配置没生效。改完配置一定要重启工具很多“改了没用”的情况都是因为进程还在用旧配置。这套工作台搭好之后你会发现 AI 编程助手的体验和“随手装一个试试”完全是两回事。前者是可持续的生产力工具后者是一次性的玩具。openrig 这类项目的意义大概就在于把前者变成一件可以复制的事。