1. 从 openrig 说起一个把 Claude Code 和 Codex 装进 tmux 的编排器第一次看到openrig这个名字我下意识把它拆成了 open rig。rig 在工程语境里指的是成套装配好的设备比如一台调试好的机器、一套搭好的工作台。放到 AI 编程工具这个场景里openrig 想干的事情就很清楚了把散落一地的 Claude Code、Codex CLI、Node.js 运行时、tmux 会话这些东西装配成一套能稳定跑起来的工作台。我接触 Claude Code 和 Codex 的时间不算短从最早在 macOS 上折腾claude code 安装到后来在 Ubuntu 服务器上配codex cli中间踩过的坑能写满一页纸。最典型的问题就是这两个工具都是终端里的常驻进程一旦 SSH 断线、终端关掉、或者本地网络抖一下正在跑的会话就没了。你让它读一个大仓库、跑一轮长任务结果中途掉线前面十几分钟的上下文全白费。tmux就是解决这个问题的老牌方案但手动把 Claude Code、Codex、Node.js 环境、代理配置、模型切换全部塞进 tmux 里每次都要重复一遍非常烦。openrig 的价值就在这里。它不是又一个 AI 编程工具而是一个编排层帮你把 Node.js 环境、Claude Code、Codex CLI、tmux 会话管理、模型接入配置这几件事一次性串起来。你不需要每次开新项目都重新npm install -g、重新配ANTHROPIC_BASE_URL、重新tmux new -s。它把这些重复劳动收敛成一套可复用的装配流程。这篇文章适合三类人看第一类是想用 Claude Code 或 Codex 但被环境配置卡住的新手尤其是卡在node.js安装、codex安装 windows桌面版、ubuntu配置claude code这些环节的第二类是已经在用、但每次都要手动开 tmux、手动切模型的进阶用户第三类是想把 AI 编程工具接入本地模型或第三方 API比如codex接入deepseek、claude code 调用lmstudio的本地模型的折腾党。我会从整体设计思路讲到具体实操把 openrig 这类编排器背后的逻辑拆开让你不光会抄作业还知道为什么这么抄。2. 整体设计思路为什么要把 Claude Code、Codex 和 tmux 绑在一起2.1 核心矛盾AI 编程工具是长会话应用而终端是短连接环境Claude Code 和 Codex CLI 的工作模式和传统的git、ls完全不一样。传统命令是执行完就退出而 Claude Code 是启动后进入一个交互式会话持续读文件、跑命令、维护上下文。这个会话可能持续几分钟也可能持续几小时。Codex CLI 同理它需要维持一个和模型端点的长连接中间还要处理流式响应。问题在于终端本身不是为长会话设计的。你本地开一个终端窗口跑 Claude Code合上笔记本、切个 Wi-Fi、SSH 超时会话就断了。更麻烦的是Claude Code 和 Codex 都会在本地维护会话状态和上下文缓存断线重连后不一定能恢复到原来的状态。我实测过一次断线重连后Claude Code 对之前读过的文件记忆基本清空得重新喂一遍。tmux 解决的就是这个会话持久化问题。它把终端进程跑在一个独立的 server 里你的终端窗口只是附着上去的一个客户端。客户端断了server 里的进程照跑。下次tmux attach回去Claude Code 还在原地等你。这是 openrig 把 tmux 作为基础设施的第一个理由。2.2 第二个理由多工具并行需要窗口管理实际干活的时候你很少只跑一个工具。典型场景是一个 tmux 窗口跑 Claude Code 做代码审查另一个窗口跑 Codex 做单元测试生成第三个窗口开着npm run dev看实时日志。如果不用 tmux你就得开三个终端窗口切来切去还容易搞混哪个窗口在跑什么。openrig 这类编排器的设计思路是把 tmux 的 window 和 pane 当作工作区来组织。一个 session 对应一个项目session 里的不同 window 对应不同工具。这样你tmux attach -t myproject进去整个项目的工作环境就回来了不用重新cd、重新启动工具。2.3 第三个理由Node.js 版本和全局包管理是重灾区Claude Code 和 Codex CLI 都是 Node.js 生态的工具通过npm install -g安装。这里有个非常隐蔽的坑不同版本的 Node.js 对这两个工具的支持程度不一样。热词里出现的error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava就是典型症状——你照着某个教程敲了nvm install 24.21.0结果这个版本根本不存在或者还没发布。openrig 的思路是把 Node.js 版本管理也纳入编排范围。它不直接依赖系统全局的 Node.js而是通过nvm或fnm这类版本管理器为每个项目锁定一个经过验证的 Node.js LTS 版本。这样你在这个项目里跑 Claude Code在另一个项目里跑别的工具互不干扰。我个人的经验是Claude Code 和 Codex 在 Node.js 20 LTS 和 22 LTS 上表现最稳24.x 虽然新但偶尔会有原生模块编译问题。2.4 方案选型对比为什么不直接用 Docker 或 VS Code 任务有人会问既然要环境隔离和会话持久化为什么不用 Docker或者直接用 VS Code 的 task 功能Docker 的问题在于重。Claude Code 需要访问你的项目文件、需要调用本地模型端点、需要读写~/.claude配置目录这些在容器里都要额外挂载和配置。而且 Docker 里的 tmux 和宿主机的 tmux 是两套东西attach 体验很割裂。对于个人开发者来说Docker 的隔离收益抵不上配置成本。VS Code task 的问题在于绑死在编辑器上。Claude Code 和 Codex 的核心使用场景是终端很多人就是喜欢在纯终端里干活。VS Code 的集成终端虽然也能跑但它的会话生命周期跟着编辑器走编辑器一关就没了还是绕不开 tmux。openrig 选择的是轻编排路线不引入容器不绑定编辑器就在宿主机上用 tmux 版本管理器 配置模板把工具串起来。这个选择牺牲了一点隔离性换来的是极低的配置成本和接近原生的使用体验。对于个人和小团队来说这个取舍是划算的。3. 核心细节解析Node.js、Claude Code、Codex 三件套的装配要点3.1 Node.js 环境版本选择与安装方式Node.js 是整个装配链的地基。Claude Code 和 Codex CLI 都依赖它装错了后面全崩。热词里node.js是干什么的、node.js官网下载、node.js lts下载、安装node.js这些搜索量很高说明很多新手卡在这一步。先说版本选择。Node.js 的发布节奏是偶数版本进 LTS长期支持奇数版本是过渡版。截至我写这篇文章20.x 和 22.x 是稳定的 LTS 线。Claude Code 官方对 Node.js 的最低要求是 18.x但实测 18.x 在跑一些新特性时会有警告建议直接上 20 LTS 或 22 LTS。安装方式我强烈建议用版本管理器不要用系统包管理器直接装。原因很简单系统包管理器装的 Node.js 是全局唯一的你没法为不同项目切换版本。而nvmNode Version Manager或fnmFast Node Manager可以让你在项目目录里nvm use 20就切过去。# 安装 nvm以 bash 为例 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并切换到 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v # 应输出 v20.x.x npm -v注意如果你在 Ubuntu 上遇到nvm: command not found大概率是~/.bashrc没加载。检查~/.bashrc末尾是否有 nvm 的初始化脚本没有就手动加上。fnm是另一个选择用 Rust 写的启动比 nvm 快很多适合经常开新 shell 的人。安装方式# 安装 fnm curl -fsSL https://fnm.vercel.app/install | bash # 安装 Node.js 20 fnm install 20 fnm use 20 fnm default 20我个人的取舍是如果你只是偶尔配一次环境nvm 够用如果你每天要开十几个终端fnm 的启动速度优势很明显。3.2 Claude Code 安装全局包与配置目录Claude Code 的安装本身很简单一条命令npm install -g anthropic-ai/claude-code但安装完之后有几个关键点要注意。第一是全局包路径。用 nvm 装的 Node.js全局包会装在~/.nvm/versions/node/v20.x.x/lib/node_modules/下面。如果你之前用系统 Node.js 装过 Claude Code现在切到 nvm 后可能找不到命令。解决办法是npm install -g重装一遍或者检查which claude指向哪里。第二是配置目录。Claude Code 的配置默认在~/.claude/下包括settings.json、会话历史、项目级配置等。这个目录很重要你的 API 端点、模型选择、权限设置都在里面。openrig 这类编排器通常会把这个目录纳入版本管理或者备份范围避免换机器后重新配。第三是环境变量。Claude Code 支持通过环境变量覆盖配置常用的有环境变量作用示例值ANTHROPIC_API_KEYAPI 密钥sk-ant-xxxANTHROPIC_BASE_URL自定义端点http://localhost:1234CLAUDE_CODE_MODEL指定模型claude-sonnet-4-20250514HTTP_PROXY网络代理http://127.0.0.1:7890热词里claude code 调用lmstudio的本地模型就是通过ANTHROPIC_BASE_URL指向 LM Studio 的本地端点实现的。LM Studio 默认监听http://localhost:1234你把它填进ANTHROPIC_BASE_URLClaude Code 就会把请求发到本地模型。3.3 Codex CLI 安装和 Claude Code 的差异点Codex CLI 的安装命令是npm install -g openai/codex它和 Claude Code 有几个关键差异配置时要注意。差异一配置文件位置。Codex 的配置在~/.codex/下主配置文件是config.tomlTOML 格式不是 JSON。这个格式差异经常让新手困惑热词里codex is ignoring 1 unrecognized configuration setting. check for typos or d就是配置文件写错格式导致的。差异二模型端点配置方式。Codex 通过config.toml里的model_provider字段配置端点而不是纯环境变量。一个典型的接入第三方 API 的配置长这样# ~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY然后在环境变量里设置DEEPSEEK_API_KEY。热词里codex接入deepseek就是这套配置。差异三登录方式。Codex 支持两种认证一种是 OpenAI 账号登录codex login一种是 API Key。如果你用的是第三方端点必须走 API Key 方式账号登录会失败。热词里codex无法加载组织设置、your organization has disabled claude subscription access for claude code这类报错很多都是认证方式选错导致的。3.4 tmux 会话编排window 和 pane 的命名规范tmux 是 openrig 的骨架。用得好不好关键在命名规范。我见过太多人开了一堆 tmux session名字叫0、1、2过两天自己都不知道哪个是哪个。我的建议是三层命名session 用项目名window 用工具名pane 用具体任务名。# 创建项目 session tmux new-session -d -s myproject -n claude # 在 claude window 里启动 Claude Code tmux send-keys -t myproject:claude cd ~/projects/myproject claude C-m # 新建 codex window tmux new-window -t myproject -n codex tmux send-keys -t myproject:codex cd ~/projects/myproject codex C-m # 新建 dev window 跑开发服务器 tmux new-window -t myproject -n dev tmux send-keys -t myproject:dev cd ~/projects/myproject npm run dev C-m这样你tmux attach -t myproject进去Ctrl-b w就能看到 claude、codex、dev 三个 window一目了然。提示tmux 默认的前缀键是Ctrl-b如果你觉得别扭可以在~/.tmux.conf里改成Ctrl-aset -g prefix C-a。改完记得tmux source-file ~/.tmux.conf重载。4. 实操过程从零搭一套 openrig 风格的工作环境4.1 环境准备清单与检查脚本在动手之前先确认你的系统里有哪些东西、缺哪些东西。我写了一个检查脚本跑一遍就知道环境齐不齐#!/bin/bash echo 环境检查 # 检查 Node.js if command -v node /dev/null; then echo [OK] Node.js: $(node -v) else echo [缺失] Node.js 未安装 fi # 检查 npm if command -v npm /dev/null; then echo [OK] npm: $(npm -v) else echo [缺失] npm 未安装 fi # 检查 tmux if command -v tmux /dev/null; then echo [OK] tmux: $(tmux -V) else echo [缺失] tmux 未安装 fi # 检查 Claude Code if command -v claude /dev/null; then echo [OK] Claude Code: $(claude --version 2/dev/null || echo 已安装) else echo [缺失] Claude Code 未安装 fi # 检查 Codex if command -v codex /dev/null; then echo [OK] Codex: $(codex --version 2/dev/null || echo 已安装) else echo [缺失] Codex 未安装 fi # 检查 nvm if command -v nvm /dev/null || [ -s $HOME/.nvm/nvm.sh ]; then echo [OK] nvm 已安装 else echo [缺失] nvm 未安装 fi把这段存成check-env.shchmod x check-env.sh后跑一遍。缺什么补什么别跳步。4.2 分步安装Node.js、tmux、Claude Code、Codex第一步装 tmux。Ubuntu/Debian 用sudo apt install tmuxmacOS 用brew install tmux。装完tmux -V验证。第二步装 nvm 和 Node.js 20 LTS。按 3.1 节的命令走。装完node -v应该是v20.x.x。第三步装 Claude Code。npm install -g anthropic-ai/claude-code claude --version如果claude --version报command not found检查npm config get prefix的输出是否在PATH里。nvm 环境下一般没问题。第四步装 Codex CLI。npm install -g openai/codex codex --version第五步配置认证。Claude Code 用claude login或设置ANTHROPIC_API_KEYCodex 用codex login或配置~/.codex/config.toml里的 API Key。4.3 用 tmux 编排多工具会话的完整脚本下面这个脚本是我实际在用的把它存成openrig.sh每次开新项目跑一遍整个工作环境就搭好了#!/bin/bash # openrig.sh - 一键搭建 AI 编程工作环境 # 用法: ./openrig.sh 项目名 项目路径 PROJECT_NAME${1:-aiproject} PROJECT_PATH${2:-$HOME/projects/$PROJECT_NAME} # 检查项目路径 if [ ! -d $PROJECT_PATH ]; then echo 项目路径不存在: $PROJECT_PATH exit 1 fi # 如果 session 已存在直接 attach if tmux has-session -t $PROJECT_NAME 2/dev/null; then echo Session $PROJECT_NAME 已存在正在 attach... tmux attach -t $PROJECT_NAME exit 0 fi # 创建 session 和第一个 windowClaude Code tmux new-session -d -s $PROJECT_NAME -n claude tmux send-keys -t $PROJECT_NAME:claude cd $PROJECT_PATH C-m tmux send-keys -t $PROJECT_NAME:claude claude C-m # 创建 Codex window tmux new-window -t $PROJECT_NAME -n codex tmux send-keys -t $PROJECT_NAME:codex cd $PROJECT_PATH C-m tmux send-keys -t $PROJECT_NAME:codex codex C-m # 创建 shell window日常命令 tmux new-window -t $PROJECT_NAME -n shell tmux send-keys -t $PROJECT_NAME:shell cd $PROJECT_PATH C-m # 创建 dev window开发服务器按需启用 tmux new-window -t $PROJECT_NAME -n dev tmux send-keys -t $PROJECT_NAME:dev cd $PROJECT_PATH C-m # 回到第一个 window tmux select-window -t $PROJECT_NAME:claude # attach tmux attach -t $PROJECT_NAME这个脚本的关键设计点先检查 session 是否存在存在就直接 attach避免重复创建每个 window 都先cd到项目路径保证工作目录一致最后select-window回到 claude windowattach 进去就是主工作区。4.4 模型接入配置本地模型与第三方 APIClaude Code 接本地 LM Studio 的配置# 在 tmux 的 claude window 里启动前设置环境变量 export ANTHROPIC_BASE_URLhttp://localhost:1234 export ANTHROPIC_API_KEYlm-studio # LM Studio 不校验随便填 claudeCodex 接 DeepSeek 的配置~/.codex/config.tomlmodel deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY然后export DEEPSEEK_API_KEYsk-xxx再启动codex。注意第三方端点的兼容性参差不齐。Claude Code 对端点的要求是兼容 Anthropic Messages API 格式Codex 要求兼容 OpenAI Chat Completions 格式。如果你接的端点返回格式不对会出现cc switch local proxy failed while handling codex endpoint /responses这类报错。排查方法是先用curl直接打端点确认返回格式。5. 常见问题与排查技巧实录5.1 安装类问题速查表报错信息根本原因解决方法error installing 24.21.0: node.js v24.21.0 is not yet released指定的 Node.js 版本不存在改用nvm install --lts装最新 LTScommand not found: claude全局包路径不在 PATH检查npm config get prefix重装codex is ignoring 1 unrecognized configuration settingconfig.toml 字段名拼错对照官方文档逐字段核对codex无法加载组织设置认证方式与端点不匹配第三方端点改用 API Key 认证your organization has disabled claude subscription access账号权限问题改用 API Key 或检查账号订阅状态cc switch local proxy failed while handling codex endpoint端点返回格式不兼容用 curl 验证端点返回格式5.2 会话类问题tmux 断线、窗口丢失、进程僵死tmux 最常见的问题是attach 回去发现窗口没了。这通常是因为 window 里的进程退出了tmux 默认会关闭这个 window。解决办法是在~/.tmux.conf里加set -g remain-on-exit on这样进程退出后 window 还在你能看到退出前的输出方便排查。另一个问题是进程僵死。Claude Code 或 Codex 卡住不响应Ctrl-C也杀不掉。这时候别急着tmux kill-session先Ctrl-b ddetach 出来然后tmux list-panes -t myproject -F #{pane_pid} #{pane_current_command}找到僵死进程的 PID用kill -9单独杀掉。这样不会影响其他 window。5.3 模型接入类问题端点不通、格式不兼容、超时端点不通的排查顺序先curl打端点根路径确认服务活着再curl打具体 API 路径确认返回格式最后检查环境变量是否在 tmux 会话里生效。这里有个坑tmux 的 window 是在创建时继承环境变量的如果你在创建 session 之后才export新变量已经存在的 window 里是看不到的。解决办法是在openrig.sh里把export写在tmux new-session之前或者用tmux send-keys在 window 里重新 export。超时问题通常是网络或模型端负载导致的。Claude Code 和 Codex 都有超时配置可以在配置文件里调大。但更根本的解决办法是长任务拆成短任务别让单次请求跑太久。5.4 我踩过的三个坑第一个坑在 tmux 里用 nvm 切换版本不生效。原因是 nvm 是 shell 函数不是可执行文件tmux 新建 window 时用的是非交互式 shell不会加载~/.bashrc里的 nvm 初始化。解决办法是在~/.bashrc顶部加[ -z $PS1 ] return之前确保 nvm 初始化脚本被加载或者直接在openrig.sh里用绝对路径调用 node。第二个坑Claude Code 的会话历史存在~/.claude/下换机器后全丢。我现在的做法是把这个目录纳入 dotfiles 仓库管理只提交settings.json和项目级配置会话历史不提交太大且含敏感信息。第三个坑Codex 的 config.toml 用 JSON 语法写。TOML 和 JSON 长得很像但 TOML 的字符串用双引号、布尔值是小写true/false、数组用方括号。我一开始把model_provider写成了model_provider: deepseekCodex 直接忽略了这个字段报unrecognized configuration setting。改回 TOML 语法就好了。6. 进阶玩法把 openrig 思路扩展到更多场景6.1 多项目并行session 隔离与资源分配当你同时跑三个项目每个项目都要开 Claude Code 和 Codex内存和 CPU 会吃紧。我的做法是给每个 session 限制资源用systemd-run或者cgroup把 tmux server 的资源占用框住。更简单的办法是不活跃的项目tmux detach后把里面的 Claude Code 进程Ctrl-C停掉需要时再重启。tmux 的 window 还在只是进程不跑了attach 回去重新启动工具即可。6.2 配置版本化把 dotfiles 和 openrig 脚本纳入 Git~/.claude/settings.json、~/.codex/config.toml、~/.tmux.conf、openrig.sh这四个文件是我必纳入 Git 的。用一个 dotfiles 仓库管理换机器时git clonestow或者软链接十分钟就能恢复完整环境。注意 API Key 不要提交用环境变量或者.env文件.env加进.gitignore。6.3 自动化启动开机自启与快捷键绑定我给我的 shell 配了一个别名op指向openrig.sh。然后在 iTerm2 或 Windows Terminal 里配一个快捷键一键打开项目工作区。更进一步可以用tmux-resurrect插件让 tmux 在重启后自动恢复上次的 session 布局。这个插件配合 openrig 的命名规范效果很好——重启机器后tmux attach进去claude、codex、dev 三个 window 原样恢复。6.4 团队协作共享 tmux 会话与配置模板tmux 支持多客户端 attach 同一个 session这意味着你可以和同事共享一个会话一起看 Claude Code 的输出。远程协作时一个人操作另一个人旁观比截图发消息高效得多。配置模板方面把openrig.sh和配置文件模板放进团队仓库新人 clone 下来跑一遍脚本就能上手省去大量你这个怎么配的的沟通成本。我个人在实际操作中的体会是openrig 这类编排器的核心价值不在于它做了多复杂的事而在于它把每次都要重复的配置劳动收敛成了一次性的装配。Node.js 版本、tmux 会话、Claude Code 和 Codex 的认证配置这些东西单独看都不难但组合起来、每天重复就是实打实的时间消耗。把它脚本化、模板化之后你省下的不只是配置时间还有配置错了导致工具跑不起来的排查时间。最后再分享一个小技巧在openrig.sh里加一行tmux set-option -t $PROJECT_NAME status-style bgcolour235,fgcolour136给不同项目的 tmux 状态栏换个颜色多项目并行时一眼就能分清哪个窗口属于哪个项目。