1. 从“openrig”说起一个把终端 AI 编码工具串起来的开源脚手架第一次看到openrig这个名字我下意识把它拆成了 “open” 和 “rig” 两半。rig 在工程语境里是“装配、搭台子”的意思比如一台矿机、一套直播设备都可以叫 rig。所以 openrig 本质上就是一套开源的装配台——它不生产模型也不发明协议而是把散落在终端里的几个 AI 编码工具Claude Code、Codex CLI 这类用一套统一的目录结构、配置约定和会话管理方式“架”起来让它们能在一个终端工作流里协同干活。我接触终端 AI 编码工具的时间不算短从最早把 Claude Code 装进 WSL到后来在 macOS、Ubuntu 上反复折腾 Codex CLI中间踩过的坑基本能写一本小册子Node.js 版本对不上、tmux会话被误杀、代理配置写错导致请求打到错误端点、组织权限被禁用、配置文件里多了一个逗号就整个 CLI 罢工。这些问题单看都是小事但叠在一起足以让一个想认真写代码的人一上午都在修环境而不是写业务。openrig想解决的正是这个痛点。它把 Claude Code、Codex 这类工具的安装、配置、会话托管、模型切换收敛到一套可复现的“装配流程”里。你可以把它理解成一个面向终端 AI 编码工具的 dotfiles 加强版不只是同步配置文件还负责拉起tmux会话、注入环境变量、管理多套模型后端本地 LM Studio、远程 API、第三方兼容端点并且在工具升级、Node.js 版本变动时给出可回滚的路径。这篇文章适合三类人看。第一类是刚听说 Claude Code、Codex CLI想在自己机器上跑起来但被 Node.js、tmux、代理配置劝退的新手第二类是已经在用但每次换机器、换系统都要重新配一遍想找一套可复用方案的老手第三类是对“终端 AI 工作流”这个方向感兴趣想看看别人是怎么把多个 CLI 工具编排到一起的工程师。我会围绕 openrig 这个装配思路把核心设计、关键细节、实操步骤和踩坑经验完整讲一遍尽量做到你照着做就能复现。2. openrig 的整体设计思路与选型考量2.1 为什么是“装配台”而不是“一体化客户端”市面上不缺一体化的 AI 编码客户端图形界面、插件、IDE 集成都有。但终端派工程师的需求很具体要在 SSH 里能用、要能脚本化、要能跟现有 shell 工作流无缝拼接。一体化客户端往往把模型、协议、界面绑死换一个模型后端就要等官方支持这在需要频繁切换本地模型和远程模型的场景里非常难受。openrig 选择“装配台”路线核心判断是工具会变装配逻辑相对稳定。Claude Code 今天用这个配置格式明天可能改Codex CLI 的端点路径可能从/responses换成别的。但“把工具装好、把会话托管好、把环境变量注入好”这件事的逻辑是不变的。所以 openrig 把易变的部分具体工具的配置做成可替换的模块把稳定的部分会话管理、环境隔离、版本检查做成核心。这个取舍带来的直接好处是当 Claude Code 或 Codex 升级导致配置不兼容时你只需要改一个模块文件而不是重装整个环境。坏处是初期理解成本略高需要你先接受“装配”这个心智模型。我的经验是只要你用过一次tmux加 shell 脚本管理开发环境这个模型十分钟就能上手。2.2 核心组件拆解Node.js、tmux、CLI 工具、模型后端openrig 的装配对象可以拆成四层从下往上依次是运行时、会话层、工具层、模型层。运行时层是 Node.js。Claude Code 和 Codex CLI 都是 Node.js 生态的工具对 Node 版本有要求。热词里出现的error installing 24.21.0: node.js v24.21.0 is not yet released就是典型的版本问题——你指定的版本号在镜像源里还不存在安装直接失败。openrig 的做法是锁定一个经过验证的 LTS 版本并在装配前做版本探测避免装到一半才发现版本不对。会话层是tmux。为什么终端 AI 工具需要tmux因为这类工具往往是长会话、交互式的一次编码任务可能持续几十分钟中间你要去看日志、跑测试、切窗口。如果直接在前台跑一个误触 CtrlC 就把会话杀了上下文全丢。tmux让会话脱离终端存在断线重连后还能接着聊。openrig 把每个工具会话放进独立的tmuxwindow命名规则统一方便脚本定位。工具层是 Claude Code、Codex CLI 这些具体工具。openrig 不修改工具本身只负责安装、配置注入和启动参数拼装。这样工具升级时openrig 的改动面很小。模型层是后端。可以是本地 LM Studio 暴露的 OpenAI 兼容端点也可以是远程 API还可以是第三方兼容服务。openrig 把模型配置抽成独立的 profile切换模型就是切换 profile不用改工具本身的配置。2.3 配置即代码目录结构与约定openrig 的目录结构大致是这样的基于常见实践整理具体以你实际拿到的版本为准openrig/ ├── profiles/ # 模型后端配置 │ ├── local-lmstudio.env │ ├── remote-api.env │ └── thirdparty.env ├── tools/ # 各工具的装配脚本 │ ├── claude-code.sh │ └── codex.sh ├── sessions/ # tmux 会话定义 │ └── default.conf ├── scripts/ │ ├── bootstrap.sh # 首次装配 │ ├── doctor.sh # 环境体检 │ └── switch.sh # 切换 profile └── README.md这个结构的关键在于约定优于配置。profiles/下的每个.env文件就是一套模型后端定义switch.sh读取文件名就能切换。tools/下的脚本只做一件事确保工具装好、配置写好、能启动。doctor.sh是体检脚本检查 Node 版本、tmux是否存在、配置文件语法、端点连通性。我特别喜欢doctor.sh这个设计。终端 AI 工具出问题时80% 的情况是环境问题而不是工具 bugNode 版本不对、tmux没装、环境变量没导出、端点写错。有一个体检脚本能把排查时间从半小时压到两分钟。2.4 与热词里那些报错的对应关系热词里有一堆报错其实都能映射到 openrig 的设计点上cc switch local proxy failed while handling codex endpoint /responses—— 这是模型后端切换时端点路径不匹配。openrig 的 profile 里会明确写清 base URL 和路径前缀避免拼接错误。your organization has disabled claude subscription access—— 这是账号权限问题openrig 的 doctor 脚本会提示你检查登录状态和权限而不是让你在工具里瞎试。codex is ignoring 1 unrecognized configuration setting—— 配置文件里有工具不认识的字段。openrig 的配置模板只包含经过验证的字段减少这类警告。note: claude code might not be available in your country—— 这是可用性提示openrig 会在文档里说明哪些后端在哪些网络环境下更稳妥但不涉及任何网络规避手段。把这些报错集中管理是 openrig 相对“手动装一遍”的最大价值。手动装的时候每个报错都要现查用 openrig报错先过一遍 doctor大部分能直接定位。3. 核心细节解析与实操要点3.1 Node.js 版本管理别用系统自带的这是我最想强调的一点。不要用系统包管理器装的 Node.js 去跑 Claude Code 或 Codex。Ubuntu 的apt install nodejs给的版本往往偏旧macOS 用 Homebrew 装的又可能太新而 Claude Code 和 Codex 对 Node 版本有明确区间要求。热词里node.js v24.21.0 is not yet released这种报错就是版本管理没做好导致的。我的做法是用版本管理器nvm或fnm都行。以nvm为例# 安装 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 nvm alias default lts/* # 验证 node -v npm -v为什么锁定 LTS 而不是追最新因为 AI 编码工具的依赖树里经常有原生模块最新版 Node 的 ABI 变动可能导致编译失败。LTS 版本经过更充分的测试踩坑概率低得多。openrig 的 bootstrap 脚本会先检测当前 Node 版本不在允许区间内就提示你切换而不是硬着头皮装。提示如果你在 Windows 上建议在 WSL2 里跑这套环境。原生 Windows 下tmux不可用会话管理会退化体验差很多。热词里claude code windows、codex安装 windows桌面版的搜索量很高但我的实测结论是 WSL2 更省心。3.2 tmux 会话托管命名、分离、重连tmux是 openrig 会话层的核心。很多人装了tmux但只用tmux new这其实浪费了它一半的能力。openrig 的用法是命名会话加脚本化定位。# 创建名为 openrig-claude 的会话直接跑 Claude Code tmux new-session -d -s openrig-claude -c ~/projects/myapp # 在会话里发送启动命令 tmux send-keys -t openrig-claude claude Enter # 需要看的时候 attach 进去 tmux attach -t openrig-claude # 临时离开但不杀会话按 Ctrlb 然后按 d命名规则统一之后你可以写脚本批量管理。比如openrig status就是遍历所有openrig-前缀的会话报告哪些在跑、哪些空闲。openrig kill就是精确杀掉指定会话不会误伤你其他tmux窗口。这里有个细节tmux的默认前缀是Ctrlb但很多人在终端里Ctrlb是光标左移容易冲突。openrig 的会话配置里会把前缀改成Ctrla跟screen一致肌肉记忆更顺。这个改动写在sessions/default.conf里attach 时用-f指定即可。注意tmux会话里的环境变量是创建时快照的。如果你在会话创建后才export新的 API key会话里是看不到的。openrig 的做法是在创建会话前就把 profile 里的变量导出或者用tmux set-environment动态注入。3.3 模型后端配置profile 隔离是关键模型后端配置最容易乱。本地 LM Studio 一个端点远程 API 一个端点第三方兼容服务又一个端点每个的 base URL、路径前缀、鉴权方式都可能不同。如果全塞在一个配置文件里改一处就可能影响另一处。openrig 用 profile 隔离。每个 profile 是一个独立的.env文件包含这几个关键变量# profiles/local-lmstudio.env OPENRIG_PROFILE_NAMElocal-lmstudio OPENRIG_BASE_URLhttp://127.0.0.1:1234/v1 OPENRIG_API_KEYlm-studio OPENRIG_MODELlocal-model-name OPENRIG_PATH_PREFIX/chat/completions切换 profile 就是source不同的文件# scripts/switch.sh 的核心逻辑 PROFILE$1 source profiles/${PROFILE}.env export OPENAI_BASE_URL${OPENRIG_BASE_URL} export OPENAI_API_KEY${OPENRIG_API_KEY} echo Switched to profile: ${OPENRIG_PROFILE_NAME}为什么要单独设OPENRIG_PATH_PREFIX因为热词里那个codex endpoint /responses报错本质就是路径拼接问题。有的后端是/v1/chat/completions有的是/v1/responses有的是/responses。把路径前缀独立出来切换后端时只改这一行不用动工具配置。3.4 配置文件语法一个逗号能毁掉一上午Claude Code 和 Codex 的配置文件通常是 JSON 或 TOML。JSON 对语法极其敏感多一个逗号、少一个引号整个文件就解析失败。热词里codex is ignoring 1 unrecognized configuration setting就是配置字段不被识别虽然不致命但说明配置和工具版本不匹配。openrig 的做法是配置模板加校验。tools/下的脚本在写入配置前先用jq或python -m json.tool校验语法# 校验 JSON 配置 if ! jq empty $CONFIG_FILE 2/dev/null; then echo Config file has syntax error: $CONFIG_FILE exit 1 fi这个检查看起来简单但能拦住绝大多数“配置写了但工具不认”的问题。我自己的习惯是任何手改配置文件之后先跑一遍校验再启动工具省得在工具里看到莫名其妙的报错。提示不同版本的 Claude Code 和 Codex 支持的配置字段不同。openrig 的模板会标注适用版本区间升级工具后如果出现unrecognized configuration setting先对照模板删掉不支持的字段而不是硬留着。4. 完整实操流程从零装配一套终端 AI 编码环境4.1 环境准备与依赖检查假设你在一台干净的 Ubuntu 22.04 或 macOS 上从零开始。第一步不是急着装 Claude Code而是把基础依赖补齐。# Ubuntu 下安装基础工具 sudo apt update sudo apt install -y curl git tmux jq build-essential # macOS 下用 Homebrew brew install curl git tmux jqbuild-essential在 Ubuntu 下是给原生模块编译用的macOS 下对应的是 Xcode Command Line Toolsbrew会自动处理。jq用来校验和操作 JSON 配置tmux是会话层git用来拉 openrig 本身。装完之后做一次体检# 检查关键命令是否存在 for cmd in node npm tmux jq git; do if command -v $cmd /dev/null 21; then echo OK: $cmd - $(command -v $cmd) else echo MISSING: $cmd fi done这一步的目的是把“缺什么”提前暴露而不是等到装 Claude Code 时报一堆错。我见过太多人跳过这步然后在npm install失败时才发现build-essential没装。4.2 安装 Node.js 并锁定版本按 3.1 节的方法装nvm然后锁定 LTS。这里补充一个细节项目级版本锁定。如果你有多个项目不同项目可能需要不同 Node 版本可以在项目根目录放一个.nvmrc# 在 openrig 目录下 echo lts/* .nvmrc # 进入目录时自动切换 nvm usenvm use会读取.nvmrc并切换到对应版本。这样你和协作者之间不会因为 Node 版本不同导致行为差异。openrig 的 bootstrap 脚本会在开始时检查.nvmrc是否存在存在就自动nvm use。4.3 装配 Claude CodeClaude Code 的安装方式以官方文档为准常见的是通过 npm 全局安装或官方安装脚本。openrig 的tools/claude-code.sh大致逻辑是#!/usr/bin/env bash set -euo pipefail # 1. 检查 Node 版本 REQUIRED_NODE_MAJOR18 CURRENT_NODE_MAJOR$(node -v | sed s/v\([0-9]*\).*/\1/) if [ $CURRENT_NODE_MAJOR -lt $REQUIRED_NODE_MAJOR ]; then echo Node version too old. Required: $REQUIRED_NODE_MAJOR exit 1 fi # 2. 安装 Claude Code以官方方式为准 npm install -g anthropic-ai/claude-code # 3. 写入配置 mkdir -p ~/.claude cat ~/.claude/config.json EOF { model: ${OPENRIG_MODEL}, baseUrl: ${OPENRIG_BASE_URL} } EOF # 4. 校验配置 jq empty ~/.claude/config.json # 5. 启动会话 tmux new-session -d -s openrig-claude -c $PWD tmux send-keys -t openrig-claude claude Enter echo Claude Code session started: openrig-claude这里有几个关键点。第一set -euo pipefail让脚本遇到错误立即退出避免半装状态。第二Node 版本检查放在最前面不满足直接退出。第三配置写入后立即用jq校验。第四会话创建和命令发送分开方便调试。4.4 装配 Codex CLICodex CLI 的装配逻辑类似但配置格式可能不同。假设它用 TOML#!/usr/bin/env bash set -euo pipefail npm install -g openai/codex mkdir -p ~/.codex cat ~/.codex/config.toml EOF model ${OPENRIG_MODEL} base_url ${OPENRIG_BASE_URL} api_key_env OPENAI_API_KEY EOF # TOML 校验可以用 python python3 -c import tomllib; tomllib.load(open($HOME/.codex/config.toml,rb)) tmux new-session -d -s openrig-codex -c $PWD tmux send-keys -t openrig-codex codex Enter echo Codex session started: openrig-codex注意api_key_env这个字段它让 Codex 从环境变量读 key而不是把 key 写死在配置文件里。这是安全实践openrig 的所有 profile 都遵循这个原则。4.5 接入本地模型以 LM Studio 为例本地模型的好处是数据不出机器、延迟低、不依赖外部服务。LM Studio 可以暴露一个 OpenAI 兼容端点默认在http://127.0.0.1:1234/v1。# profiles/local-lmstudio.env OPENRIG_PROFILE_NAMElocal-lmstudio OPENRIG_BASE_URLhttp://127.0.0.1:1234/v1 OPENRIG_API_KEYlm-studio OPENRIG_MODELqwen2.5-coder-7b-instruct OPENRIG_PATH_PREFIX/chat/completions切换到这个 profile 后Claude Code 和 Codex 都会把请求打到本地。这里有个坑本地模型的上下文窗口通常比远程模型小如果你的代码文件很大可能超出窗口导致截断。openrig 的 doctor 脚本会提示你检查模型的最大上下文长度并在配置里设置合理的max_tokens。注意本地模型的能力和远程大模型有差距适合做代码补全、简单重构、注释生成这类任务。复杂架构设计还是建议用能力更强的后端。openrig 的 profile 机制让你可以按任务切换不用重装环境。4.6 会话管理与日常使用装配完成后日常使用就是几个命令# 查看所有 openrig 会话 tmux ls | grep openrig # 进入 Claude Code 会话 tmux attach -t openrig-claude # 进入 Codex 会话 tmux attach -t openrig-codex # 切换模型后端 ./scripts/switch.sh local-lmstudio # 环境体检 ./scripts/doctor.sh我的习惯是给每个项目开一组会话命名带上项目名比如openrig-claude-myapp。这样同时做多个项目时不会混。tmux的 window 和 pane 可以进一步细分比如一个 window 跑 Claude Code一个 window 跑测试一个 window 看日志。5. 常见问题与排查技巧实录5.1 安装类问题速查报错关键词可能原因排查动作node.js v24.21.0 is not yet released指定了不存在的 Node 版本用nvm ls-remote查看可用版本改用 LTSerror installing伴随原生模块编译失败缺 build 工具链Ubuntu 装build-essentialmacOS 装 Xcode CLTnpm install -g权限错误全局目录权限问题用nvm管理 Node避免sudo npmcommand not found: claude全局 bin 不在 PATH检查npm bin -g输出是否在 PATH 里nvm的一个隐性好处是全局包装在用户目录下不需要sudo从根上避免了权限问题。如果你之前用sudo npm install -g装过东西可能会留下权限混乱的目录建议清理后重装。5.2 配置类问题排查配置问题最隐蔽因为工具报错往往不直接指向配置行。我的排查顺序是先校验语法。JSON 用jq emptyTOML 用python3 -c import tomllib...。语法错直接修。再对照版本。unrecognized configuration setting说明字段和工具版本不匹配查官方文档确认当前版本支持哪些字段。最后查端点。cc switch local proxy failed while handling codex endpoint /responses这类报错用curl直接打端点验证curl -sS ${OPENRIG_BASE_URL}${OPENRIG_PATH_PREFIX} \ -H Authorization: Bearer ${OPENRIG_API_KEY} \ -H Content-Type: application/json \ -d {model:${OPENRIG_MODEL},messages:[{role:user,content:ping}]}如果curl能通而工具不通问题在工具配置如果curl也不通问题在后端或网络。这个二分法能快速缩小范围。5.3 会话类问题排查tmux会话的常见问题是“会话还在但工具卡死”。这时候不要直接kill-session先 attach 进去看状态。如果是工具在等输入发个回车如果是网络请求卡住CtrlC中断当前请求会话本身还在。另一个常见问题是“断线后会话丢了”。这通常是因为你没用tmux而是直接在前台跑。确认一下tmux ls能不能看到会话。看不到就说明会话没建成功检查创建命令的-d参数和send-keys的目标名是否一致。提示tmux会话默认在机器重启后消失。如果你需要持久化可以用tmux-resurrect这类插件但配置略复杂。openrig 的定位是开发时会话管理不追求跨重启持久化。5.4 账号与权限类问题热词里your organization has disabled claude subscription access和claude code might not be available in your country都属于账号权限和可用性范畴。这类问题不是技术配置能解决的需要检查你的账号状态、订阅类型和组织策略。openrig 的 doctor 脚本会做基础检查能否读到 API key、key 格式是否合理、端点是否返回鉴权错误。如果返回 401 或 403脚本会提示你检查账号而不是让你在工具里反复重试。这个区分很重要——技术问题和账号问题要分开处理混在一起排查效率极低。5.5 我踩过的三个坑第一个坑用系统 Node 装 Claude Code。Ubuntu 自带的 Node 版本太旧装到一半报原生模块编译失败。换成nvm管理的 LTS 后一次通过。教训是AI 编码工具对 Node 版本敏感别省这一步。第二个坑配置文件里留了注释。JSON 不支持注释我手改配置时习惯性加了//结果工具直接解析失败。后来养成习惯改完先jq empty校验。TOML 支持注释但字段名大小写敏感也容易错。第三个坑tmux会话里环境变量过期。我在会话创建后才更新 API key结果会话里还是旧 key请求一直 401。排查了半小时才想到是环境变量快照问题。现在我的做法是改完 profile 后重建会话而不是在旧会话里折腾。6. 进阶玩法与扩展方向6.1 多项目并行会话命名与资源隔离当你同时推进多个项目时会话管理会变复杂。我的做法是用项目名-工具名的命名规则比如myapp-claude、myapp-codex、otherproj-claude。然后写一个简单的包装脚本#!/usr/bin/env bash # openrig-project.sh PROJECT$1 TOOL${2:-claude} SESSIONopenrig-${PROJECT}-${TOOL} if tmux has-session -t $SESSION 2/dev/null; then tmux attach -t $SESSION else tmux new-session -d -s $SESSION -c $HOME/projects/$PROJECT tmux send-keys -t $SESSION $TOOL Enter tmux attach -t $SESSION fi这个脚本的逻辑是会话存在就 attach不存在就创建再 attach。用起来就是./openrig-project.sh myapp claude非常顺手。6.2 模型后端热切换不重启会话理想情况下切换模型后端不应该杀掉会话。但环境变量是会话创建时的快照直接改 profile 对已存在的会话无效。一个折中方案是用tmux set-environment动态注入# 在已存在的会话里更新环境变量 tmux set-environment -t openrig-claude OPENAI_BASE_URL http://127.0.0.1:1234/v1 tmux set-environment -t openrig-claude OPENAI_API_KEY lm-studio但注意工具进程本身可能已经缓存了配置动态注入不一定生效。更可靠的做法是在工具内部支持配置重载或者接受“切换后端需要重启会话”这个约束。openrig 目前走的是后者简单可靠。6.3 与编辑器集成VS Code 里的终端热词里vscode配置claude code、vscode接入claude code搜索量很高。VS Code 的集成终端本质上就是一个 shell所以 openrig 的会话管理在 VS Code 里同样适用。你可以在 VS Code 的终端里tmux attach也可以配置 VS Code 的 task 来一键启动。我的做法是在.vscode/tasks.json里加一个 task{ version: 2.0.0, tasks: [ { label: OpenRig: Start Claude, type: shell, command: tmux attach -t openrig-claude || tmux new-session -s openrig-claude claude, problemMatcher: [] } ] }这样在 VS Code 里按CtrlShiftP运行 task 就能进会话。编辑器负责写代码终端会话负责 AI 交互两边不打架。6.4 安全与合规边界用终端 AI 编码工具时有几个边界要清楚。第一不要把敏感信息写进配置文件API key 走环境变量。第二本地模型和远程模型的数据流向不同涉及敏感代码时优先用本地模型。第三第三方兼容服务的可靠性参差不齐生产环境慎用。openrig 的 profile 机制让你能清晰区分不同后端但选择哪个后端是你的责任。注意任何工具的使用都要遵守所在组织的安全策略和相关服务条款。openrig 只做环境装配不改变工具本身的行为边界。7. 一些个人体会折腾终端 AI 编码工具这几年我最大的感受是环境问题消耗的精力远超工具本身的能力差异。Claude Code 和 Codex 谁更强可能因人而异但一个装不好的环境会让你对两个工具都失去耐心。openrig 这类装配台的价值不在于它让工具变强了而在于它把“装好、配好、能稳定跑”这件事标准化了。我现在换一台新机器从零到能跑 Claude Code 和 Codex大概十五分钟。其中大部分时间在等 npm 下载真正的手工操作就是跑几个脚本。这个效率提升不是靠某个黑科技而是靠把踩过的坑固化成检查项Node 版本、tmux存在性、配置语法、端点连通性、会话命名。每一项单独看都很小合起来就是一套可复现的流程。如果你刚开始接触这类工具我的建议是先用 openrig 的思路手动装一遍理解每一层在干什么然后再用脚本自动化。直接抄脚本而不理解原理遇到报错还是会卡住。等你手动装过两三次自然就知道哪些步骤可以固化、哪些需要按环境调整。到那时候你甚至可以写一套更适合自己工作流的装配方案openrig 只是一个起点。