1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到“openrig”这个词我脑子里蹦出来的不是某个具体软件而是一种“开放式工作台”的意象。rig 在英文里本意是“装配、搭建”在工程语境里常指一套成套的设备或装置比如 drilling rig钻机、test rig测试台。前面加个 open意思就很明确了——这是一套开放的、可自由拼装的工具台。结合热搜词里高频出现的 Claude Code、Codex、Node.js、tmux 这几个关键词我基本能判断出 openrig 的定位它大概率是一个围绕 AI 编程助手Claude Code、Codex CLI 这类终端智能体搭建的本地运行环境或编排框架把 Node.js 运行时、tmux 会话管理、模型接入配置这些东西打包成一套可复用的“工作台”。为什么我会有这个判断因为热搜词里几乎全是围绕“怎么装、怎么配、怎么接本地模型、怎么在终端里跑起来”这类问题。比如“claude code 调用 lmstudio 的本地模型”“codex 接入 deepseek”“使用 cc switch 接入 deepseek v4、qwen、glm 等模型”“ubuntu 配置 claude code”“vscode 配置 claude code”。这些问题有一个共同点它们都不是在问“这个 AI 工具好不好用”而是在问“我怎么把它跑起来、接上我自己的模型、在我的终端环境里稳定用”。这正是 openrig 这类项目要解决的痛点——把散落在各处的安装步骤、环境变量、代理配置、会话管理整合成一套开箱即用的方案。所以这篇博文我不打算把它写成一份干巴巴的 README 翻译。我想做的是把 openrig 背后涉及的核心技术点一个个拆开讲清楚每个环节为什么这么设计、踩过哪些坑、怎么验证配置是否生效。无论你是刚接触终端 AI 助手的新手还是已经折腾过几轮 Claude Code 和 Codex 的老手都能从里面找到能直接抄作业的部分。整篇内容会围绕 Node.js 环境、tmux 会话、模型接入、配置排错这几条主线展开尽量做到“看完就能动手动手就能跑通”。2. Node.js 运行时整个工作台的地基2.1 为什么这类工具几乎都绑死在 Node.js 上Claude Code、Codex CLI 这类终端 AI 助手绝大多数都是基于 Node.js 生态构建的。原因其实不复杂Node.js 的 npm 生态是目前分发命令行工具最成熟的渠道一条npm install -g就能把工具装到全局跨平台一致性也好。而且这类工具需要频繁发起 HTTP 请求调用模型 API、处理流式响应streaming、管理本地文件读写Node.js 的异步 I/O 模型天然适合这种场景。但这也意味着Node.js 的版本管理成了整个工作台的第一道坎。热搜词里有一条特别典型“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”。这个报错我见过太多次了本质上是版本号写错了或者用了某个还没正式发布的版本号去安装。Node.js 的版本发布有严格的节奏偶数版本是 LTS长期支持奇数版本是 Current尝鲜版而且每个大版本下面还有一堆小版本。你如果随手写一个24.21.0很可能这个补丁号根本不存在。我的建议很直接生产环境一律用 LTS 版本不要追 Current。截至我写这篇内容的时候Node.js 20.x 和 22.x 都是稳定的 LTS 线。安装方式上我强烈推荐用版本管理器而不是直接下安装包。Windows 上用 nvm-windowsmacOS/Linux 上用 nvm 或 fnm。原因很简单AI 编程工具更新极快今天要 Node 18明天可能就要求 Node 20用版本管理器切换只要一行命令不用反复卸载重装。# 以 nvm 为例安装并切换到 LTS 版本 nvm install --lts nvm use --lts node -v # 确认版本号应该是 v20.x 或 v22.x npm -v # 确认 npm 也能正常工作2.2 安装 Node.js 时最容易忽略的三个细节第一个细节是全局安装路径的权限问题。在 Linux 和 macOS 上如果你直接用系统自带的 Node.js 或者用 sudo 装 npm 包很容易遇到EACCES权限错误。正确的做法是配置 npm 的全局目录到用户目录下避免每次都要 sudomkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加到 PATH 里 export PATH~/.npm-global/bin:$PATH第二个细节是网络镜像源。国内直接连 npm 官方源有时候会慢到让人怀疑人生配置一个可靠的镜像源能省很多时间。但要注意有些镜像源同步不及时装最新版的 AI 工具可能会失败。我的经验是日常装包用镜像遇到版本找不到的情况再切回官方源试试。npm config set registry https://registry.npmmirror.com # 需要时切回官方 npm config set registry https://registry.npmjs.org第三个细节是Node.js 版本和工具要求的匹配。很多人在装 Claude Code 或 Codex 的时候报错排查半天发现是 Node.js 版本太低。这类工具通常要求 Node 18 以上部分新版本甚至要求 Node 20。装之前先看一眼官方文档的 engines 字段能省掉大量无效排查。2.3 验证 Node.js 环境是否真的可用装完 Node.js 不代表环境就绪了。我习惯做三步验证第一node -v和npm -v都能正常输出版本号第二随便建一个临时目录npm init -y然后npm install一个小包确认网络和权限都没问题第三全局装一个命令行工具再卸载确认全局路径配置正确。mkdir /tmp/node-test cd /tmp/node-test npm init -y npm install lodash --no-save npm install -g cowsay cowsay node ok npm uninstall -g cowsay这三步走完基本能排除 90% 的环境问题。如果这一步就有报错那后面装 AI 工具肯定也跑不起来先把地基打牢再说。3. tmux让 AI 助手在后台稳定干活的秘密武器3.1 为什么终端 AI 工具和 tmux 是天生一对热搜词里 tmux 和 Claude Code、Codex 并列出现这不是偶然。tmux 是一个终端复用器它最核心的能力是让你在一个 SSH 会话里开多个窗口、多个面板而且会话可以脱离当前终端独立存在。这对 AI 编程助手来说太重要了。想象一个场景你让 Claude Code 帮你重构一个模块它需要跑测试、读文件、改代码整个过程可能持续好几分钟。如果你直接在前台终端跑一旦网络抖动或者你不小心关了窗口任务就中断了。但如果你把它跑在 tmux 会话里即使你断开 SSH、关掉笔记本盖子任务依然在后台跑着回来tmux attach就能看到完整输出。这就是 tmux 的核心价值——会话持久化。另一个价值是多任务并行。你可以开一个 tmux 窗口跑 Claude Code 做代码审查另一个窗口跑 Codex 写测试用例第三个窗口开着日志监控。三个任务互不干扰切换只要一个快捷键。这种工作流一旦用顺了就再也回不去了。3.2 tmux 的基础操作够用就好别背手册tmux 的快捷键很多但实际高频使用的就那么几个。我整理了一张表把最常用的操作列出来新手记住这些就能覆盖 95% 的场景。操作快捷键说明新建会话tmux new -s 名字给会话起个有意义的名字方便找回断开会话Ctrlb然后ddetach会话继续在后台跑列出会话tmux ls查看当前所有会话重新连接tmux attach -t 名字回到指定会话水平分屏Ctrlb然后上下分两个面板垂直分屏Ctrlb然后%左右分两个面板切换面板Ctrlb然后方向键在面板间移动关闭面板Ctrlb然后x会提示确认这里有个新手常踩的坑tmux 的前缀键默认是Ctrlb但有些终端环境里这个组合被占用了。如果你按了没反应可以在~/.tmux.conf里改成别的比如改成Ctrla# ~/.tmux.conf set -g prefix C-a unbind C-b bind C-a send-prefix改完配置后在 tmux 里执行tmux source-file ~/.tmux.conf让配置生效。3.3 用 tmux 管理 AI 助手会话的实战套路我自己的习惯是给每个长期任务开一个独立会话命名规则是“项目名-任务类型”。比如projA-review、projB-test。这样tmux ls一眼就能看出哪个会话在干什么。启动 Claude Code 或 Codex 的时候我会先建会话再在里面跑命令tmux new -s projA-review # 进入会话后 cd /path/to/project claude # 或者 codex取决于你用哪个工具然后Ctrlb d断开让它自己在后台跑。需要看进度的时候再tmux attach -t projA-review。如果任务跑完了直接在里面exit退出会话自动销毁。还有一个进阶技巧用 tmux 的日志功能记录 AI 助手的完整输出。有时候 AI 给出的建议很长翻屏就找不到了。你可以在 tmux 里开启日志# 在 tmux 会话中按 Ctrlb 然后 : # 输入下面的命令把输出记录到文件 pipe-pane -o cat ~/claude-session.log这样所有输出都会追加到日志文件里事后可以慢慢翻。排查问题的时候特别有用因为你能看到 AI 助手到底执行了哪些命令、返回了什么结果。4. 模型接入本地模型和第三方 API 的配置逻辑4.1 Claude Code 和 Codex 的模型接入机制差异这是很多人容易搞混的地方。Claude Code 和 Codex CLI 虽然都是终端 AI 助手但它们接入模型的方式不太一样。Claude Code 默认走的是 Anthropic 官方的模型服务配置主要通过环境变量或者配置文件来指定 API 端点和密钥。如果你想让它调用本地模型比如 LM Studio 跑起来的模型就需要把端点指向本地的 OpenAI 兼容接口。热搜词里“claude code 调用 lmstudio 的本地模型”说的就是这个场景。Codex CLI 则更灵活一些它本身就支持配置不同的模型提供商。热搜词里“codex 接入 deepseek”“使用 cc switch 接入 deepseek v4、qwen、glm 等模型”反映的就是这种需求——通过一个中间层比如 cc switch 这类代理工具把请求转发到不同的模型服务上。这里要特别说明接入第三方模型服务时一定要确认该服务提供的是 OpenAI 兼容接口。目前绝大多数本地推理框架LM Studio、Ollama 等和第三方模型服务都提供 OpenAI 兼容的/v1/chat/completions端点这是事实上的行业标准。配置的时候主要就是改 base URL 和 API key 两个参数。4.2 配置本地模型接入的完整步骤以 LM Studio 为例我梳理一遍完整流程。假设你已经在本地跑起了 LM Studio并且加载了一个模型。第一步在 LM Studio 里启动本地服务器。默认端口是 1234接口地址是http://localhost:1234/v1。确认服务器启动后可以用 curl 测一下curl http://localhost:1234/v1/models如果返回了模型列表说明服务正常。第二步配置 Claude Code 或 Codex 使用这个端点。具体方式取决于工具版本通常是通过环境变量export OPENAI_BASE_URLhttp://localhost:1234/v1 export OPENAI_API_KEYlm-studio # 本地模型通常不校验 key随便填一个或者在工具的配置文件里指定。不同版本的配置字段名可能不同建议以官方文档为准。第三步验证接入是否成功。启动工具后问一个简单问题看它是否能正常返回。如果报连接错误先检查 LM Studio 的服务器是否还在跑如果报模型不存在检查模型名称是否写对。注意本地模型的上下文窗口通常比云端模型小很多。如果你让 AI 助手读一个大文件可能会超出上下文限制导致报错。这种情况下要么换更大的模型要么把任务拆小。4.3 第三方 API 接入时的常见报错与排查热搜词里有一条很典型的报错“cc switch local proxy failed while handling codex endpoint /responses”。这个错误信息透露了几个关键点一是用了 cc switch 这类本地代理工具二是代理在处理 Codex 的/responses端点时失败了。这类问题的排查思路我总结成三步第一确认代理服务本身是否在运行。本地代理工具挂了后面什么都免谈。检查进程、检查端口占用。第二确认端点路径是否正确。不同工具用的 API 路径可能不一样有的是/v1/chat/completions有的是/v1/responses。代理工具需要正确转发这些路径如果配置里写错了路径就会 404。第三确认请求格式是否匹配。有些模型服务对请求体的字段有要求比如必须带model字段、messages格式必须规范。代理工具如果做了格式转换转换逻辑出错也会导致失败。排查的时候最有效的手段是看代理工具的日志。把日志级别调到 debug然后复现一次请求日志里通常会明确告诉你哪一步出了问题。报错现象可能原因排查方向连接被拒绝代理服务没启动检查进程和端口404 Not Found端点路径配置错误核对 API 路径401 UnauthorizedAPI key 无效或缺失检查密钥配置400 Bad Request请求格式不匹配查看请求体字段超时网络问题或模型响应慢检查网络和模型负载5. 配置排错那些让人抓狂的报错到底在说什么5.1 “organization has disabled claude subscription access” 的来龙去脉热搜词里有一条“your organization has disabled claude subscription access for claude code”。这个报错的意思是你当前登录的账号所属的组织禁用了通过订阅方式访问 Claude Code 的权限。这种情况通常出现在企业或团队账号环境下。管理员可能在后台关闭了某个功能开关导致成员无法使用。遇到这个报错你自己在本地怎么折腾都没用因为问题出在账号权限层面。解决办法要么是联系管理员开通权限要么换一个个人账号使用。我之所以把这个报错单独拿出来讲是因为它代表了一类问题有些报错不是技术问题而是权限或策略问题。新手容易陷入“是不是我配置错了”的自我怀疑实际上跟你没关系。遇到这类报错先看清楚错误信息的措辞如果出现 organization、subscription、access 这类词大概率是账号层面的限制。5.2 “ignoring unrecognized configuration setting” 该怎么处理另一个高频报错是“codex is ignoring 1 unrecognized configuration setting. check for typos or d...”。这个相对友好它明确告诉你配置文件里有一个它不认识的字段被忽略了让你检查拼写。这种情况一般发生在工具升级之后。新版本可能改了配置字段名或者删掉了某个旧字段而你的配置文件还是老版本的。解决办法就是对照官方文档把配置文件的字段名更新一遍。我的习惯是每次升级 AI 工具后先跑一次--help或者查看官方 changelog确认配置格式有没有变化。很多问题在升级前就能预判到不用等到报错了才去查。5.3 一个完整的排错案例从报错到跑通我拿自己遇到过的一次真实问题来演示排查链路。当时的情况是Codex CLI 启动后一直提示连接失败但网络是通的API key 也确认没问题。第一步我看错误信息它说的是连接超时。于是我先用 curl 直接测 API 端点curl -v https://api.example.com/v1/models -H Authorization: Bearer $API_KEY结果 curl 也超时。这说明问题不在 Codex而在网络层面。第二步我检查了代理设置。发现终端环境里有一个HTTP_PROXY环境变量指向了一个已经失效的地址。Codex 读取了这个变量把所有请求都往那个失效地址发自然超时。第三步清除失效的代理变量重新测试unset HTTP_PROXY unset HTTPS_PROXY curl -v https://api.example.com/v1/models -H Authorization: Bearer $API_KEY这次 curl 正常返回了。再启动 Codex问题解决。这个案例的教训是排查问题要一层层往下剥先用最基础的工具curl验证底层连通性再去看上层应用。如果一上来就盯着 Codex 的配置改可能改半天都找不到真正的原因。6. 编辑器集成在 VS Code 里用 AI 助手的正确姿势6.1 VS Code 集成终端 AI 助手的两种模式热搜词里“vscode 配置 claude code”“claude code for vs code”“vscode 接入 claude code”出现频率很高。这说明很多人希望在 VS Code 里直接用这些工具而不是切到独立终端。目前主要有两种集成模式。第一种是在 VS Code 的集成终端里直接跑 CLI 工具。VS Code 内置的终端本质上就是一个终端模拟器你在里面跑claude或codex跟在系统终端里跑没区别。这种模式最简单不需要额外配置。第二种是通过 VS Code 扩展集成。有些工具提供了官方或社区的 VS Code 扩展能在编辑器界面里直接调用 AI 能力比如在侧边栏聊天、右键菜单触发代码解释等。这种模式体验更原生但配置可能复杂一些。我的建议是先用第一种模式跑通确认工具本身能正常工作再去折腾扩展。因为扩展本质上也是调用底层 CLI如果 CLI 本身有问题装再多扩展也没用。6.2 在 VS Code 终端里跑 AI 助手的环境变量陷阱这里有一个很容易踩的坑VS Code 集成终端的环境变量可能和你系统终端不一样。特别是在 macOS 上如果你是通过图形界面启动 VS Code 的它可能不会加载你 shell 配置文件.zshrc、.bashrc里的环境变量。这意味着你在系统终端里配好的OPENAI_API_KEY、OPENAI_BASE_URL这些变量在 VS Code 终端里可能是空的。工具启动后找不到 key就会报认证失败。解决办法有两个。一是从终端启动 VS Codecode /path/to/project这样 VS Code 会继承当前 shell 的环境变量。二是把环境变量配置写到 VS Code 能读到的地方比如在项目的.env文件里定义或者用 VS Code 的terminal.integrated.env.*设置。// settings.json { terminal.integrated.env.linux: { OPENAI_API_KEY: your-key-here } }注意把 API key 写在 settings.json 里要注意文件权限别不小心提交到 git 仓库了。更安全的做法是用系统钥匙串或者专门的密钥管理工具。6.3 让 AI 助手在 VS Code 里真正提效的几个习惯光把工具跑起来还不够得让它真正融入工作流。我分享几个自己常用的习惯。第一个习惯是用 VS Code 的任务tasks功能封装常用命令。比如把“启动 Claude Code 做代码审查”定义成一个任务绑定快捷键一键触发。// .vscode/tasks.json { version: 2.0.0, tasks: [ { label: Claude Code Review, type: shell, command: claude, args: [--review], problemMatcher: [] } ] }第二个习惯是把 AI 助手的输出和编辑器的问题面板结合。有些工具支持输出 JSON 格式的审查结果你可以写个小脚本把它转换成 VS Code 能识别的问题格式这样代码问题会直接标在编辑器里点击就能跳转。第三个习惯是用工作区workspace隔离不同项目的配置。不同项目可能用不同的模型、不同的 API 端点把这些配置放在工作区的.vscode/settings.json里切换项目时自动切换配置不用手动改环境变量。7. 把这些串起来一套可复用的 openrig 式工作流7.1 从零搭建一套终端 AI 工作台的完整清单把前面几节的内容串起来我给出一份从零开始的搭建清单。这份清单假设你是一台全新的机器什么都没装。第一步装 Node.js 版本管理器然后用它装 LTS 版本的 Node.js。验证node -v和npm -v正常。第二步配置 npm 全局目录和镜像源避免权限问题和网络问题。第三步装 tmux配置前缀键和基础设置确认能正常建会话、分屏、断开重连。第四步全局安装你需要的 AI 工具比如npm install -g anthropic-ai/claude-code或者对应的 Codex 包。具体包名以官方文档为准。第五步配置模型接入。如果用官方服务配置 API key如果用本地模型启动本地推理服务并配置端点。第六步在 tmux 会话里启动工具跑一个简单任务验证全链路通畅。第七步配置 VS Code 集成确认编辑器终端里也能正常使用。这份清单看起来步骤不少但每一步都有明确的验证方法出问题能快速定位到是哪一环。7.2 日常使用中的经验沉淀用了一段时间之后我积累了一些让工作流更顺滑的经验。会话命名要有规律。我见过有人开了一堆 tmux 会话名字都是默认的 0、1、2过两天完全不知道哪个是哪个。用“项目-任务”的命名规则tmux ls一眼就能找到目标。日志要留。AI 助手的输出有时候很有价值特别是它给出的代码建议和排查思路。用 tmux 的 pipe-pane 或者工具自带的日志功能把输出存下来事后能翻。配置要版本化。把 tmux 配置、工具配置、环境变量模板都放到一个 dotfiles 仓库里换机器的时候一键恢复不用重新踩一遍坑。升级要谨慎。AI 工具迭代快新版本可能改了配置格式或者行为。升级前先看 changelog升级后跑一遍验证流程确认没问题再正式用。7.3 遇到问题时的高效求助方式最后说说遇到问题怎么求助。我观察到一个现象很多人报错的时候只贴一句“跑不起来”别人想帮都无从下手。高效的求助应该包含这些信息你用的工具和版本号完整的报错信息不要截断你执行的命令你的环境操作系统、Node.js 版本你已经尝试过的排查步骤把这些信息整理清楚不管是去社区提问还是搜解决方案效率都会高很多。而且整理信息的过程本身往往就能帮你发现问题所在——我有好几次就是在写清楚排查步骤的时候突然意识到自己漏了哪一步。这套 openrig 式的工作流核心思想就是把环境搭稳、把会话管好、把配置理清、把问题查透。工具会不断更新但这套方法论是通用的。你把 Node.js、tmux、模型接入、排错这几块吃透了以后不管出什么新的终端 AI 工具都能快速上手。