openrig 编排 Claude Code 与 Codex：tmux 持久化与本地模型接入实战

1. 从 openrig 说起一个把 Claude Code 和 Codex 装进 tmux 的编排器第一次看到openrig这个名字我下意识把它拆成了 “open” 和 “rig” 两截。rig 在工程语境里是“装配、搭台子”的意思比如把一堆设备、线缆、工具组装成一套能干活的工作台。放到 AI 编程助手这个场景里openrig 干的事情其实非常直白它把 Claude Code、Codex 这类命令行 AI 编程工具连同 Node.js 运行时、tmux 会话管理、本地模型接入这些零散部件装配成一套可以长期稳定运行的工作环境。如果你最近在折腾 Claude Code 或者 Codex大概率踩过这些坑Node.js 版本对不上装到一半报error installing 24.21.0: node.js v24.21.0 is not yet released or is not availableCodex 启动后提示codex is ignoring 1 unrecognized configuration settingClaude Code 在 VS Code 里能跑切到终端就找不到命令想用 tmux 挂后台跑长任务结果会话一关进程就没了。这些问题单看都不难但凑在一起就非常消耗耐心。openrig 的价值就在于它把这些碎片化的配置动作收敛成一套可复现的流程让你不用每次换机器都从头翻文档。这篇文章适合三类人看第一类是刚接触 Claude Code、Codex连 Node.js 是干什么的都还没完全搞清楚的入门玩家第二类是已经在用 CLI 工具但被 tmux 会话管理、本地模型接入、第三方 API 切换折腾得够呛的进阶用户第三类是想把 AI 编程助手做成团队标准环境需要一套可复制方案的技术负责人。我会从整体设计思路讲到具体操作把每个关键选择背后的理由说清楚再把我自己踩过的坑和排查技巧一并交出来。2. openrig 的整体设计与思路拆解2.1 为什么需要一层“编排”而不是直接装工具很多人会问Claude Code 和 Codex 本身都有安装脚本为什么还要多一层 openrig答案在于“环境一致性”和“会话持久化”这两件事。直接装工具你得到的是一个能跑的命令用 openrig 编排你得到的是一套可描述、可重建、可后台运行的环境。我举个实际场景。你在本地用 Claude Code 调 LM Studio 的本地模型跑一个重构任务中途需要关掉终端去开会。如果直接在前台跑终端一关任务就断了。openrig 的思路是把 Claude Code 或 Codex 放进 tmux 会话里tmux 负责维持进程你随时可以 detach 再 attach 回来。这个设计看起来简单但它决定了你能不能把 AI 编程助手当成一个“常驻服务”来用而不是一个随开随关的临时命令。另一个理由是版本管理。Node.js 的版本迭代很快Claude Code 和 Codex 对 Node.js 版本有各自的要求。openrig 把 Node.js 的安装和版本选择纳入统一管理避免出现“这个工具要 20.x那个工具要 22.x”的冲突。它通常会借助 nvm 或者 fnm 这类版本管理器把不同项目锁在不同 Node.js 版本上。2.2 核心组件选型Node.js、tmux、CLI 工具三者如何配合openrig 的组件关系可以用一句话概括Node.js 是地基Claude Code 和 Codex 是住在地基上的两个住户tmux 是物业负责让住户 24 小时不断电。Node.js 在这里的角色是运行时。Claude Code 和 Codex 的 CLI 版本大多是基于 Node.js 生态分发的所以 Node.js 装不对后面全白搭。我建议用 LTS 版本而不是追最新的 Current 版本。原因很实际LTS 版本经过更长时间验证第三方库兼容性更好。你在网上看到的node.js v24.21.0 is not yet released这类报错往往就是因为安装脚本里写死了一个还没正式发布的版本号。tmux 的角色是会话保持。它允许你在一个终端窗口里创建多个会话每个会话可以独立运行进程并且支持 detach 和 attach。对于 AI 编程助手这种“任务跑起来可能要十几分钟甚至更久”的场景tmux 几乎是刚需。你可以早上启动一个 Codex 任务中午回来 attach 看结果中间该干嘛干嘛。Claude Code 和 Codex 则是实际干活的工具。Claude Code 偏向于和 Claude 系列模型配合Codex 则更通用一些可以接入 DeepSeek、Qwen、GLM 等第三方模型。openrig 要做的就是让这两个工具在同一套环境里和平共处互不干扰。2.3 本地模型接入与第三方 API 的取舍逻辑openrig 另一个值得说的设计点是模型接入层。现在用 Claude Code 或 Codex不一定非要走官方订阅。很多人会选择接入 LM Studio 的本地模型或者通过 cc switch 这类工具切换到 DeepSeek、Qwen、GLM 的第三方 API。本地模型的优势是数据不出本机适合处理敏感代码劣势是对硬件有要求推理速度取决于你的显卡和内存。第三方 API 的优势是省硬件、速度快劣势是数据要经过网络传输且需要管理 API Key。openrig 的思路是把这两种接入方式都做成可切换的配置而不是二选一。你可以在处理普通任务时用第三方 API处理敏感代码时切到本地模型。这里有个细节要注意Claude Code 调用 LM Studio 的本地模型时需要 LM Studio 开启兼容 OpenAI 的 API 服务并且 Claude Code 的配置里要指向本地的 endpoint。这个 endpoint 通常是http://localhost:1234/v1这类地址。配置错了就会出现连接失败或者模型列表为空的问题。3. 核心细节解析与实操要点3.1 Node.js 安装版本选择与常见报错处理Node.js 是 openrig 环境里最底层的一环也是最容易出问题的一环。我先说版本选择。截至我写这篇文章的时候Node.js 的 LTS 版本是 20.x 和 22.x 两个大版本。Claude Code 和 Codex 对这两个版本的支持都比较好。如果你没有特殊需求直接选 22.x 的 LTS 版本就行。安装方式上我不建议直接从官网下载安装包双击安装。原因是你以后可能会遇到需要切换 Node.js 版本的情况用安装包装的话切换起来很麻烦。更好的做法是用版本管理器Linux 和 macOS 上用 nvmWindows 上可以用 nvm-windows 或者 fnm。用 nvm 安装 Node.js 的命令很简单nvm install 22 nvm use 22 nvm alias default 22这三条命令分别做三件事安装 22 版本、切换到 22 版本、把 22 设为默认版本。第三条命令很多人会漏掉结果新开终端又回到了旧版本。如果你在安装过程中遇到error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错说明你用的安装脚本或者某个工具的依赖里写死了一个不存在的版本号。解决办法是手动指定一个已发布的版本比如nvm install 22.11.0。不要盲目相信脚本里的默认版本号尤其是那些很久没更新的脚本。还有一个常见问题是权限。在 Linux 和 macOS 上如果你用sudo安装 Node.js后面用 npm 装全局包时可能会遇到权限错误。我的建议是全程不用sudo用 nvm 装到用户目录下这样最省心。3.2 tmux 会话管理让 AI 任务在后台稳定运行tmux 的用法不复杂但有几个关键操作必须掌握。我按使用频率从高到低说。创建新会话tmux new -s claude。这条命令创建一个名为 claude 的会话。名字很重要因为后面你要靠名字来识别和恢复会话。分离会话在 tmux 会话里按Ctrlb松开后再按d。这样你就从会话里退出来了但会话里的进程还在跑。查看会话列表tmux ls。这条命令列出当前所有会话包括会话名、窗口数、创建时间。恢复会话tmux attach -t claude。这条命令重新连接到名为 claude 的会话。关闭会话在会话里输入exit或者用tmux kill-session -t claude。我实际用下来最实用的组合是创建一个专门跑 Claude Code 的会话再创建一个专门跑 Codex 的会话。这样两个工具互不干扰你可以随时切换。比如tmux new -s claude-code # 在会话里启动 Claude Code tmux new -s codex # 在会话里启动 Codex有个坑要提醒tmux 会话里的环境变量可能和你登录 shell 的环境变量不一致。如果你在.bashrc或.zshrc里配置了 API Keytmux 会话里可能读不到。解决办法是在 tmux 配置文件里加上set-option -g update-environment API_KEY或者直接在会话里重新 export 一次。3.3 Claude Code 与 Codex 的安装与配置差异Claude Code 和 Codex 虽然都是 AI 编程助手但安装和配置上有一些差异这些差异如果不注意很容易让人困惑。Claude Code 的安装通常是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后你需要配置 API Key 或者登录账号。如果你用的是官方订阅直接按提示登录即可。如果你要接入第三方 API 或者本地模型就需要修改配置文件。Claude Code 的配置文件通常在~/.claude/config.json或者项目目录下的.claude文件夹里。Codex 的安装方式类似但包名和配置路径不同。Codex 的配置文件里有一个常见的坑codex is ignoring 1 unrecognized configuration setting. check for typos or d这个报错意思是你的配置文件里有一个它不认识的配置项。这通常是因为你参考了旧版本的文档或者复制了别人的配置但没改全。解决办法是逐项核对配置项名称把不认识的删掉或者改成正确的名称。另一个差异是模型接入。Claude Code 默认走 Claude 系列模型接入第三方模型需要额外的适配层。Codex 对第三方模型的支持更直接一些通过配置 base URL 和 API Key 就能切换。比如接入 DeepSeek{ model: deepseek-chat, base_url: https://api.deepseek.com/v1, api_key: your-api-key }这里要注意base URL 的结尾不要多加/也不要少写/v1否则会出现 404 或者连接失败。3.4 本地模型接入LM Studio 与 Claude Code 的配合用 Claude Code 调用 LM Studio 的本地模型是我最近用得比较多的方案。它的好处是数据完全不出本机适合处理公司内部代码。操作步骤是这样的。第一步打开 LM Studio在“Local Server”标签页里加载一个模型比如 Qwen2.5-Coder 或者 DeepSeek-Coder。第二步启动本地服务器默认端口是 1234。第三步确认 API 地址是http://localhost:1234/v1。第四步在 Claude Code 的配置里把 base URL 指向这个地址API Key 随便填一个非空字符串即可因为本地服务器通常不校验 Key。这里有个细节LM Studio 的本地服务器默认只监听 localhost。如果你在容器或者虚拟机里跑 Claude Code需要让 LM Studio 监听0.0.0.0否则连不上。另外模型加载后要等它完全就绪再发请求否则会出现超时。实测下来本地模型的响应速度取决于你的硬件。我用一张 12GB 显存的显卡跑 7B 参数的代码模型生成速度大概在每秒 20 到 30 个 token日常补全和简单重构够用但复杂任务还是建议用云端模型。4. 实操过程与核心环节实现4.1 从零搭建 openrig 环境的完整流程我把整个搭建过程分成六个阶段按顺序执行基本不会出问题。第一阶段安装基础工具。在 Ubuntu 上先更新包列表然后安装 git、curl、tmuxsudo apt update sudo apt install -y git curl tmux在 macOS 上用 Homebrew 安装brew install git curl tmux第二阶段安装 Node.js 版本管理器。Linux 和 macOS 上用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash安装完成后重新打开终端或者执行source ~/.bashrc让 nvm 生效。第三阶段安装 Node.js LTS 版本nvm install 22 nvm use 22 nvm alias default 22 node -v最后一条命令应该输出v22.x.x如果不是说明默认版本没设置成功。第四阶段安装 Claude Code 和 Codexnpm install -g anthropic-ai/claude-code npm install -g openai/codex安装完成后分别执行claude --version和codex --version确认安装成功。第五阶段配置 tmux 会话。创建一个启动脚本比如~/start-ai.sh#!/bin/bash tmux new-session -d -s claude-code tmux send-keys -t claude-code claude C-m tmux new-session -d -s codex tmux send-keys -t codex codex C-m这个脚本会创建两个后台会话分别启动 Claude Code 和 Codex。执行chmod x ~/start-ai.sh给它加上执行权限。第六阶段验证。执行tmux ls应该能看到两个会话。执行tmux attach -t claude-code应该能看到 Claude Code 的界面。4.2 关键配置文件的参数说明与修改方法openrig 环境里涉及好几个配置文件我挑最重要的几个说。Claude Code 的配置文件。全局配置在~/.claude/config.json项目级配置在项目根目录的.claude/config.json。项目级配置会覆盖全局配置。常用的配置项包括apiKey、baseUrl、model。如果你要接入第三方 API把baseUrl改成对应的地址apiKey改成你的 Key。Codex 的配置文件。通常在~/.codex/config.json或者项目目录下的.codex文件夹里。Codex 的配置项命名和 Claude Code 不完全一样比如它可能用base_url而不是baseUrl。这就是为什么会出现unrecognized configuration setting报错——你把 Claude Code 的配置项名直接搬到 Codex 里了。tmux 的配置文件。在~/.tmux.conf。我建议加上这几行set -g mouse on set -g history-limit 10000 set -g base-index 1第一行开启鼠标支持第二行把历史记录上限调到 10000 行第三行让窗口编号从 1 开始而不是 0。这些都是提升使用体验的小改动。4.3 用 cc switch 切换第三方模型的实操记录cc switch 是一个用来切换 Claude Code 模型接入点的工具。它的核心功能是帮你管理多套配置一键切换。安装 cc switch 通常也是通过 npmnpm install -g cc-switch安装完成后你可以添加多个配置档案。比如一个档案指向 DeepSeek一个档案指向 Qwen一个档案指向本地 LM Studio。切换的时候执行cc-switch use deepseek这条命令会把当前 Claude Code 的配置切换到 DeepSeek 档案。我实际用下来cc switch 最方便的地方是它帮你管理了 API Key 和 base URL 的对应关系不用手动改配置文件。但它也有个坑切换配置后已经运行的 Claude Code 会话不会自动重载配置你需要重启会话才能生效。所以我的习惯是切换配置后直接 kill 掉旧会话重新创建一个。4.4 在 VS Code 里配置 Claude Code 的注意事项很多人习惯在 VS Code 里用 Claude Code。VS Code 的集成终端和系统终端有一些差异这些差异会导致配置不生效。第一个差异是环境变量。VS Code 的集成终端可能不会加载你 shell 的完整配置文件。如果你在.zshrc里配置了 API KeyVS Code 终端里可能读不到。解决办法是在 VS Code 的设置里加上terminal.integrated.env.linux或对应的平台配置把需要的环境变量显式传进去。第二个差异是 Node.js 版本。VS Code 可能使用系统默认的 Node.js而不是 nvm 管理的版本。你可以在 VS Code 终端里执行which node确认一下。如果路径不对需要在 VS Code 设置里指定 Node.js 的路径。第三个差异是 tmux。VS Code 的集成终端对 tmux 的支持不如系统终端完整有时候会出现显示错乱。如果你主要用 tmux 管理会话建议还是在系统终端里操作VS Code 只用来写代码。5. 常见问题与排查技巧实录5.1 安装类问题速查表报错信息可能原因解决办法node.js v24.21.0 is not yet released安装脚本写死了未发布版本手动指定已发布版本如nvm install 22.11.0npm install -g权限错误用了 sudo 或系统级 Node.js改用 nvm 安装全程不用 sudoclaude: command not foundnpm 全局 bin 目录不在 PATH 里把~/.nvm/versions/node/v22.x.x/bin加入 PATHcodex is ignoring 1 unrecognized configuration setting配置文件里有 Codex 不认识的项逐项核对配置项名称删除或改正cc switch local proxy failed while handling codex endpoint /responses代理配置和 Codex 的 endpoint 不匹配检查 cc switch 的代理设置确认 endpoint 路径正确5.2 运行类问题排查思路运行类问题里最常见的是连接失败和模型不响应。连接失败的表现是 Claude Code 或 Codex 启动后发请求一直转圈或者直接报错。排查顺序是这样的先确认网络能通用curl测试 API 地址再确认 API Key 有效可以用一个最简单的请求测试最后确认 base URL 的路径正确特别是/v1有没有漏掉。模型不响应的表现是请求发出去了但迟迟没有返回。如果是本地模型先确认 LM Studio 的服务器在运行模型已加载完成。如果是第三方 API可能是触发了速率限制等几分钟再试。还有一个隐蔽的问题是时区。某些 API 服务会根据请求头里的时间戳做校验如果你的系统时间不对请求会被拒绝。用date命令确认系统时间准确。5.3 我踩过的三个坑和对应的避坑技巧第一个坑是 Node.js 版本冲突。我一开始用系统自带的 Node.js后来装了 nvm结果新终端里node -v显示的还是旧版本。原因是 nvm 的初始化脚本没有加到 shell 配置文件里。解决办法是在.bashrc或.zshrc里加上 nvm 的初始化代码并确保它在 PATH 设置之前执行。第二个坑是 tmux 会话里的环境变量丢失。我在.zshrc里配置了 API Key但在 tmux 会话里启动 Claude Code 时提示 Key 无效。后来发现 tmux 启动时会创建一个新的 shell这个 shell 不一定加载了.zshrc。解决办法是在 tmux 配置文件里加上set-option -g default-shell /bin/zsh并确保.zshrc里的配置对非交互式 shell 也生效。第三个坑是 cc switch 切换后配置不生效。我以为切换完就能直接用结果发现 Claude Code 还是走旧配置。原因是 Claude Code 在启动时读取配置运行中不会重载。解决办法是切换配置后重启 Claude Code 会话。5.4 性能优化与资源占用控制openrig 环境跑起来后资源占用主要来自三个方面Node.js 进程、tmux 会话、本地模型。Node.js 进程本身占用不大但如果同时跑多个 Claude Code 和 Codex 实例内存会累积。我的建议是不要开太多会话按需创建用完就 kill。tmux 会话本身占用很小但会话里的历史记录会占内存。把history-limit设成 10000 行是个平衡点再大就有点浪费了。本地模型是资源大户。如果你用 LM Studio 跑本地模型显存占用取决于模型大小。7B 模型大概需要 6 到 8GB 显存13B 模型需要 10 到 12GB。如果显存不够模型会部分加载到内存速度会明显下降。我的经验是如果显卡显存小于 8GB就别折腾本地模型了直接用第三方 API 更省心。6. 一些实际使用中的体会openrig 这套东西我用了大概三个月最大的感受是它把“能用”和“好用”之间的差距填上了。以前每次换机器或者重装系统配 Claude Code 和 Codex 都要花小半天现在有了这套流程半小时就能搞定。另一个体会是 tmux 的价值被很多人低估了。大家觉得 tmux 是个老古董但用在 AI 编程助手这个场景里它恰好解决了“任务跑一半终端关了”这个痛点。我现在习惯是早上到工位第一件事就是tmux attach看看昨晚跑的任务有没有结果。最后分享一个小技巧如果你经常需要在多个模型之间切换可以给每个模型建一个 tmux 会话会话名就用模型名。比如tmux new -s deepseek、tmux new -s qwen。这样你想用哪个模型直接 attach 对应会话就行不用改配置。这个做法看起来有点笨但实际用起来非常顺手尤其是当你需要对比不同模型的输出时。