1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了两半open和rig。rig在工程语境里通常指“成套装置”“装配好的工作台”在软件圈子里它更多指代“一套可复用的运行骨架”。把这两个词拼在一起意思就很直白了——一套开放的、可自由拼装的运行骨架。结合热搜词里高频出现的 Claude Code、Codex、Node.js、tmux 这几个关键词我基本能判断出openrig的定位它是一套围绕命令行 AI 编码工具CLI Agent搭建的本地运行环境编排方案核心目标是把 Claude Code、Codex 这类工具的运行依赖、会话管理、终端复用统一收拢到一个可复现的骨架里。为什么这件事值得单独做一个项目因为凡是真正在终端里长期用 Claude Code 或 Codex 干活的人都会撞上同一堵墙这些工具本身是 Node.js 生态里的 CLI 程序跑起来依赖 Node 版本、依赖终端会话的持久性、依赖本地模型或第三方 API 的接入配置。单装一个还能忍一旦你想同时跑 Claude Code 和 Codex甚至想让它们共享同一套本地模型后端环境就开始互相打架。openrig要做的就是把这堆零散的安装、配置、会话保持、模型接入动作抽象成一套“装配说明书”让你换一台机器也能在十几分钟内把整套工作台立起来。这篇文章适合谁看如果你只是偶尔在网页上点点 AI 对话那这里的内容对你意义不大。但如果你属于下面这几类人这篇东西值得你从头读到尾第一类想在本地终端里把 Claude Code 和 Codex 都跑起来但被 Node 版本、安装报错、登录配置卡住的开发者第二类想让这些 CLI 工具接上本地模型比如通过 LM Studio 暴露的本地推理服务或者第三方 API 的人第三类需要长时间跑任务、希望会话不因为终端关闭而中断想用 tmux 做会话托管的人。openrig的价值不在于它发明了什么新东西而在于它把这一整套“装配流程”沉淀下来了而我要做的是把这个骨架背后的每一颗螺丝拧给你看。需要先说明一点openrig这个项目本身在公开渠道的资料非常少项目正文和关键词都是空的所以我接下来的内容是基于热搜词所反映的真实使用场景结合一名长期在终端里折腾 CLI Agent 的从业者的常见实践做合理还原和补全。凡是涉及具体命令和配置的地方我都会明确标注这是“常见做法”你可以直接抄也可以按自己的环境微调。2. 装配之前先想清楚Node.js 版本与运行时的地基怎么打2.1 为什么 Node.js 版本是这类工具的第一道坎Claude Code 和 Codex 的 CLI 都是 Node.js 程序这意味着它们对运行时版本有硬性要求。热搜词里有一条特别扎眼error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错信息本身就说明了很多问题——很多人在安装时习惯性地去追最新版本号结果撞上了一个还没正式发布的版本安装器直接拒绝。这类报错的根因不是网络问题也不是权限问题而是版本号根本不存在于官方发布列表里。我在实际装配中总结出的第一条经验是永远优先选 LTS 版本不要追奇数版本也不要追还没进 LTS 的大版本号。Node.js 的发布节奏是偶数大版本进 LTS奇数大版本是过渡性的实验版本。对于 Claude Code、Codex 这种需要长期稳定运行的工具LTS 是唯一合理的选择。热搜词里出现的node.js lts下载、node.js官网下载正是这个需求的体现。具体怎么操作去 Node.js 官网下载 LTS 版本的安装包Windows 用户拿.msimacOS 用户拿.pkgLinux 用户建议用版本管理工具而不是直接装系统包。为什么 Linux 上推荐版本管理工具因为系统自带的 Node 往往版本偏旧而你用apt或yum装的版本又可能和项目需要的版本冲突。用nvmNode Version Manager这类工具可以做到“一个项目一个 Node 版本”互不干扰。# 安装 nvm常见做法具体脚本以官方仓库为准 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并切换到某个 LTS 版本 nvm install --lts nvm use --lts # 验证 node -v npm -v装完之后一定要验证node -v和npm -v都能正常输出。我见过太多“装完了但 PATH 没生效”的案例表现就是新开一个终端窗口node命令又找不到了。这种情况八成是环境变量写进了当前 shell 的临时配置而没有写进~/.bashrc或~/.zshrc。判断方法很简单关掉终端重新开一个再敲node -v如果报 command not found就是 PATH 没持久化。2.2 npm 全局目录与权限那些“装上了却跑不起来”的隐形坑Node 装好只是第一步接下来是全局安装 CLI 工具。这里有个高频坑在 Linux 和 macOS 上直接用npm install -g装全局包有时会因为权限问题写到系统目录导致要么装不进去要么装进去了但普通用户执行不了。热搜词里codex无法加载组织设置、your organization has disabled claude subscription access这类报错虽然表面看是账号和组织策略问题但排查时第一步永远是确认“工具本身是不是真的装好了、版本对不对”。我的做法是给 npm 配一个用户级的全局目录彻底绕开系统权限# 创建用户级全局目录 mkdir -p ~/.npm-global # 配置 npm 使用该目录 npm config set prefix ~/.npm-global # 把该目录加入 PATH写进 ~/.bashrc 或 ~/.zshrc export PATH~/.npm-global/bin:$PATH # 重新加载配置 source ~/.bashrc这样配置之后npm install -g装的东西都落在你自己的家目录里不需要 sudo也不会污染系统环境。这个习惯一旦养成后面装 Claude Code、Codex 或者任何其他 CLI 工具都会顺很多。提示如果你之前用 sudo 装过全局包建议先清理掉旧的全局目录避免新旧两套路径打架。清理前先npm root -g看一眼当前全局目录在哪确认无误再动手。2.3 网络与镜像安装慢、装到一半断掉的应对思路安装 Node 包时最常见的体验问题就是慢和断。这不是openrig特有的问题而是所有依赖 npm 生态的工具都会遇到的。合理的做法是配置一个稳定的镜像源把下载速度拉起来。这里我不展开具体镜像地址因为不同地区、不同网络环境下最优选择不一样你可以根据自己的实际情况选择官方源或可信的镜像源。配置方式很简单# 查看当前源 npm config get registry # 设置为某个镜像源示例按需替换 npm config set registry 镜像源地址 # 恢复官方源 npm config set registry https://registry.npmjs.org/判断源是否生效可以装一个小包测试比如npm install -g cowsay看下载速度是否正常。如果换了源还是慢那问题可能出在 DNS 解析或者本地网络策略上这时候可以考虑用nrm这类源管理工具快速切换对比。3. Claude Code 与 Codex 的安装、登录与配置拆解3.1 Claude Code 的安装路径与常见报错定位Claude Code 的安装主流方式是通过 npm 全局安装。装完之后第一次运行会引导你登录。热搜词里claude code安装、claude code下载安装、claude code windows、ubuntu配置claude code这些词说明跨平台安装是大家最关心的点。安装命令通常是这样的npm install -g anthropic-ai/claude-code装完之后直接敲claude启动。如果提示 command not found回到上一节检查 PATH。如果启动后卡在登录环节或者报your organization has disabled claude subscription access for claude code那基本可以确定是账号层面的订阅或组织策略问题不是本地环境问题。这类报错的排查顺序是先确认账号本身有没有对应权限再确认登录用的凭据是不是最新的最后才怀疑本地配置。还有一个热搜词值得单独说note: claude code might not be available in your country. check supported co...。这类提示本质上是服务可用性判断遇到时不要慌先确认自己的账号状态和网络环境是否满足工具的正常使用条件再决定下一步。我个人的经验是遇到这类提示时优先去官方文档核对当前支持情况而不是盲目改配置。在 VS Code 里集成 Claude Code 也是高频需求热搜词里vscode配置claude code、claude code for vs code、vscode接入claude code反复出现。常见做法是安装对应的 VS Code 扩展然后在扩展设置里填入 CLI 的路径或者直接让它调用已安装的claude命令。这里有个细节VS Code 的集成终端和系统终端的环境变量可能不一致如果 CLI 在系统终端能跑、在 VS Code 里跑不了八成是 VS Code 没继承到你的 PATH。解决办法是在 VS Code 设置里显式配置终端环境或者干脆从 VS Code 的集成终端里重新source一次配置文件。3.2 Codex 的安装与“配置不识别”类报错的根因Codex 的安装逻辑和 Claude Code 类似也是 npm 全局包。热搜词里codex安装、codex安装教程、codex安装包、codex cli、codex官网下载说明大家对安装路径的需求很集中。安装命令大致是npm install -g openai/codex装完敲codex启动。这里有个特别典型的报错codex is ignoring 1 unrecognized configuration setting. check for typos or d...。这个报错的意思是你的配置文件里有一个字段 Codex 不认识它选择忽略。很多人看到“ignoring”就以为没事其实这往往意味着你想要的某个配置根本没生效。排查这类问题的正确姿势是打开 Codex 的配置文件通常在用户目录下的配置目录里逐字段核对拼写和层级。常见错误包括把配置项写在了错误的层级、字段名大小写不对、用了旧版本才支持的字段。我的建议是配置改动一次只改一个字段改完立刻重启验证这样出问题时能精确定位到是哪一行引起的。另一个高频报错是codex无法加载组织设置。这个和 Claude Code 的组织策略报错类似属于账号或服务端配置层面。遇到时先确认账号状态再确认本地配置文件里有没有残留的旧组织信息。有时候换过账号之后旧配置没清干净就会导致加载冲突。3.3 登录态与会话保持为什么 tmux 是绕不开的一环热搜词里tmux单独出现这不是偶然。Claude Code 和 Codex 这类工具很多使用场景是“发起一个长任务然后等它慢慢跑”。如果你直接在普通终端里跑一旦网络抖动、SSH 断开、或者你不小心关了窗口会话就没了任务也就断了。tmux 解决的就是这个问题——它把终端会话托管在一个常驻的后台服务里你的窗口只是“连上去看”断开连接不影响后台任务继续跑。基本用法# 新建一个名为 work 的会话 tmux new -s work # 在会话里正常启动 claude 或 codex claude # 按 Ctrlb 然后按 d 脱离会话任务继续在后台跑 # 重新连接 tmux attach -t work # 查看所有会话 tmux ls # 结束某个会话 tmux kill-session -t work我自己的习惯是给每个长期任务单独开一个 tmux 会话命名带上日期或任务关键词比如tmux new -s codex-0415。这样一周后回来还能一眼看出哪个会话是干什么的。另外tmux 里跑 CLI 工具时建议把滚动缓冲区调大一点否则输出多了之后往回翻会丢历史。在~/.tmux.conf里加一行set -g history-limit 50000就能解决。注意tmux 会话是绑定在具体机器上的。如果你是在远程机器上跑tmux 保的是“远程机器上的会话不断”而不是“你的本地网络不断”。这一点要分清楚否则会误以为开了 tmux 就万事大吉。4. 让 CLI 接上本地模型与第三方 API配置思路与踩坑记录4.1 为什么要把 Claude Code 接到 LM Studio 的本地模型热搜词里有一条很具体claude code 调用lmstudio的本地模型。这背后的需求很清晰——不是所有人都想或者都能一直用云端模型本地模型在隐私、成本、离线可用性上有天然优势。LM Studio 这类工具可以在本地起一个兼容常见 API 格式的推理服务然后 Claude Code 通过配置指向这个本地地址就能把请求打到本地模型上。常见做法是在 LM Studio 里加载好模型启动本地服务记下它监听的地址和端口通常是本机的某个端口。然后在 Claude Code 的配置里把 API 基地址指向这个本地地址并填一个占位的 API Key本地服务通常不校验 Key但客户端要求必须填。配置大概长这样# 常见做法通过环境变量指定 API 基地址 export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlocal-placeholder这里有几个坑要提前说。第一本地模型的上下文窗口往往比云端模型小Claude Code 在处理大文件时可能会超出窗口表现为请求被截断或者报错。第二本地模型的工具调用tool use能力参差不齐有些模型对函数调用的支持不完整会导致 Claude Code 的某些功能失效。第三本地推理速度取决于你的硬件如果显存不够模型会跑到内存里速度会慢到让你怀疑人生。所以接本地模型之前先确认你的硬件能扛得住你要用的模型规模。4.2 第三方 API 接入的通用套路与 cc switch 的角色热搜词里使用cc switch 接入 deepseek v4, qwen, glm等模型、第三方api使用技巧、codex接入deepseek这几条放在一起看指向一个很明确的需求大家希望在这些 CLI 工具和不同模型供应商之间灵活切换。cc switch这类工具的作用就是帮你管理多套 API 配置一键切换而不用每次手动改环境变量。它的核心逻辑是维护一个配置文件里面存多组“供应商 地址 Key 模型名”的组合切换时把对应组合写入 CLI 工具读取的位置。这种方案的好处是可逆、可备份、可版本管理。我的建议是把这个配置文件纳入你的 dotfiles 仓库换机器时直接拉下来就能用。配置第三方 API 时最容易踩的坑是模型名不匹配。很多供应商的模型名和官方模型名不一样如果你在配置里写了官方名请求打过去会被拒绝。排查方法很简单先用 curl 直接打供应商的接口确认模型名和返回格式再写进 CLI 配置。# 用 curl 验证第三方接口是否通示例结构 curl -X POST 供应商接口地址/v1/chat/completions \ -H Authorization: Bearer 你的Key \ -H Content-Type: application/json \ -d {model:模型名,messages:[{role:user,content:ping}]}如果 curl 能通CLI 里不通那就是 CLI 配置的问题如果 curl 都不通那就是接口地址、Key 或模型名的问题。这个二分法能帮你快速缩小排查范围。4.3 本地代理转发失败的排查链路热搜词里有一条很长的报错cc switch local proxy failed while handling codex endpoint /responses. provi...。这条报错信息量很大它说明请求经过了本地代理转发但在处理 Codex 的/responses端点时失败了。这类问题的排查链路我建议按下面的顺序走排查步骤检查内容常见结论1本地代理进程是否在运行进程挂了重启即可2代理监听的端口是否和 CLI 配置一致端口写错改配置3目标端点路径是否正确/responses和/v1/responses可能不同4上游供应商是否支持该端点部分供应商只支持 chat 端点5请求体格式是否符合上游要求字段名或结构不匹配我遇到这类问题的第一反应永远是“先看代理日志”。代理工具一般都会把转发详情打到日志里包括请求路径、请求体、上游返回。看日志比猜快一百倍。如果日志里显示上游返回了 4xx那就是请求本身的问题如果显示连接超时那就是网络或上游地址的问题。还有一个容易被忽略的点有些代理工具在处理不同 CLI 的请求时会做格式转换。Claude Code 用的请求格式和 Codex 用的可能不一样代理如果转换逻辑有 bug就会在特定端点上失败。这种情况下要么升级代理工具版本要么换一个转换逻辑更成熟的方案。5. 把整套环境固化成 openrig可复现装配的实践方法5.1 为什么“能跑”和“可复现”是两回事很多人装完一套环境自己机器上跑得好好的换台机器或者过两个月重装就怎么都跑不起来了。原因很简单你当时做的很多操作是“隐式”的——手动改了个环境变量、临时装了个依赖、在某处写了个配置但都没记下来。openrig这类项目的核心价值就是把这些隐式操作显式化变成一份可执行的装配清单。我的做法是把整套环境拆成四层运行时层Node 版本、包管理器、工具层Claude Code、Codex、tmux、配置层API 地址、Key、模型名、会话层tmux 会话命名规范、日志存放位置。每一层都用一个脚本或一份配置文件描述清楚。这样重装时按层执行出问题也能快速定位到是哪一层。5.2 一份可抄的装配清单结构下面这份清单是我自己在用的结构你可以直接拿去改#!/usr/bin/env bash # openrig 装配脚本示例结构 set -e # 任何一步失败就停止避免错误累积 echo 检查 Node 版本 node -v || { echo Node 未安装请先安装 LTS 版本; exit 1; } echo 配置 npm 用户级全局目录 mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH echo 安装 CLI 工具 npm install -g anthropic-ai/claude-code npm install -g openai/codex echo 检查 tmux tmux -V || echo tmux 未安装请通过系统包管理器安装 echo 写入环境变量追加到 shell 配置 grep -q npm-global/bin ~/.bashrc || echo export PATH~/.npm-global/bin:$PATH ~/.bashrc echo 装配完成请重新加载 shell 配置后验证这份脚本的关键在于set -e和每一步的显式检查。set -e保证任何一步失败就停不会带着错误继续往下跑避免出现“装了一半”的中间状态。每一步的echo是给人看的出问题时你能立刻知道卡在哪一步。5.3 配置文件的版本管理与密钥安全配置层最容易出安全问题。API Key 这种东西绝对不能明文提交到公开仓库。我的做法是配置文件里只写占位符真实 Key 放在一个不纳入版本管理的本地文件里通过环境变量注入。比如# 在 ~/.bashrc 里引用一个本地密钥文件 [ -f ~/.openrig-secrets ] source ~/.openrig-secrets~/.openrig-secrets这个文件里写export ANTHROPIC_API_KEYxxx之类的真实值并且把它加进.gitignore。这样你的 dotfiles 仓库可以公开分享密钥却不会泄露。这个习惯看起来简单但能帮你避免很多麻烦。注意如果你在多台机器之间同步配置密钥文件要么手动同步要么用专门的密钥管理工具不要图省事直接塞进公开仓库。6. 长期使用中的稳定性维护与经验沉淀6.1 版本升级的节奏把控CLI 工具更新很频繁但我不建议一有新版就升。我的经验是在任务间隙升级不在任务进行中升级。因为升级可能带来配置格式变化、行为变化甚至引入新的 bug。升级前先看一眼更新日志确认没有破坏性变更。升级后先跑一个简单任务验证确认没问题再投入正式使用。如果升级后出问题要能快速回滚。npm 全局包可以指定版本安装# 安装指定版本 npm install -g anthropic-ai/claude-code版本号 # 查看已安装版本 npm list -g --depth0所以我的建议是在升级前记下当前版本号出问题时能立刻装回去。这个习惯在关键时刻能救你一命。6.2 日志与排查素材的留存长期使用这类工具一定要养成留日志的习惯。tmux 会话里的输出、代理工具的转发日志、CLI 自身的错误输出都是排查问题的关键素材。我的做法是给 tmux 配置日志记录把会话输出自动落盘# 在 ~/.tmux.conf 里配置日志示例思路 # 具体插件和配置按你的 tmux 版本选择即使不做自动落盘至少也要在遇到报错时手动把完整输出复制下来。很多人排查问题时只截取报错的一行结果丢失了上下文导致无法定位。完整的报错信息、完整的命令、完整的环境信息这三样凑齐问题基本就解决了一半。6.3 我踩过的几个真实坑与对应解法第一个坑在 VS Code 集成终端里跑 Claude Code登录一直失败换到系统终端就正常。根因是 VS Code 终端的环境变量和系统终端不一致导致 CLI 读到了错误的配置路径。解法是在 VS Code 设置里显式指定终端环境或者从集成终端里手动 source 一次配置。第二个坑tmux 会话里跑长任务第二天回来发现会话还在但任务早就因为某个交互式提示卡住了。根因是 CLI 工具在某些情况下会等待用户输入而 tmux 后台会话没人应答。解法是尽量用非交互模式启动任务或者在启动前确认所有需要确认的选项都已经通过配置预设好。第三个坑换了 API 供应商之后CLI 一直报模型不存在。根因是配置文件里旧供应商的模型名没清掉新配置没生效。解法是每次换供应商时把配置文件完整过一遍确认所有相关字段都更新了而不是只改其中一两个。这些坑的共同点是它们都不是工具本身的 bug而是环境配置和使用习惯的问题。openrig这类装配方案的价值恰恰在于把这些经验固化下来让后来的人少走弯路。工具会更新报错会变化但“显式化配置、分层管理、留好日志、控制升级节奏”这几条原则在很长一段时间内都不会过时。