openrig 环境编排：Claude Code 与 Codex 的 tmux 持久化部署指南

发布时间：2026/10/31 3:25:36
openrig 环境编排：Claude Code 与 Codex 的 tmux 持久化部署指南

1. 从零认识 openrig：它到底解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件支架或者开源机械臂项目。实际上，结合它周边高频出现的关键词——Claude Code、Codex、Node.js、tmux——可以判断出，openrig 是一个面向 AI 编程助手（Coding Agent）的本地运行环境编排工具。它的核心价值在于：把 Claude Code、Codex 这类命令行 AI 编程工具，和 Node.js 运行时、tmux 会话管理、本地模型服务等组件，整合成一套可复用、可切换、可远程接入的工作台。

说白了，你平时用 Claude Code 或 Codex 写代码，可能会遇到几个很烦的问题：终端一关会话就断了、多个模型供应商切换要改一堆环境变量、本地模型和云端 API 混用时配置冲突、Windows 和 Ubuntu 上安装步骤完全不一样。openrig 想做的就是把这些碎片化的操作收敛到一个统一的编排层里，让你用一条命令或者一份配置，就能把整套环境拉起来。

它适合什么人？三类人最需要它。第一类是重度使用 Claude Code 或 Codex CLI 的开发者，每天要在终端里跟 AI 结对编程好几个小时；第二类是喜欢折腾本地模型（比如通过 LM Studio 或类似方案跑本地推理）的人，需要在本地模型和云端 API 之间频繁切换；第三类是在远程服务器上做开发的工程师，需要保证 SSH 断开后 AI 会话不中断。如果你只是偶尔用网页版 AI 聊天，那 openrig 对你来说可能有点重。

我自己的使用场景是这样的：一台 Ubuntu 开发机常年开着 tmux，里面跑着 Claude Code 和 Codex 两个会话，分别接不同的模型后端。以前每次重启机器或者换项目，都要手动重新配一遍环境变量、重新登录、重新设置工作目录。用了 openrig 之后，这些步骤被固化成了配置文件，开机后一条命令就能恢复到之前的工作状态。这个体验提升是实打实的。

2. 核心组件拆解：Node.js、tmux 与 AI CLI 的三角关系

2.1 Node.js 是整个工具链的地基

Claude Code 和 Codex CLI 本质上都是 Node.js 应用，通过 npm 全局安装。所以 Node.js 的版本管理是第一步，也是最容易翻车的一步。热搜词里出现了 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这种报错，说明很多人在安装时直接指定了一个不存在的版本号。

我的建议是：不要追最新版，用 LTS 版本。截至我写这篇内容时，Node.js 20.x 和 22.x 的 LTS 版本对 Claude Code 和 Codex 的兼容性最稳。安装方式上，Ubuntu 用户可以用 NodeSource 的 apt 源，Windows 用户直接去 Node.js 官网下载 LTS 的 msi 安装包。如果你需要多个 Node 版本共存，用 nvm 或者 fnm 来管理，别手动改 PATH，否则后面 npm 全局包路径会乱成一团。

注意：安装完 Node.js 后，务必确认npm config get prefix的输出路径在你的用户目录下，而不是系统目录。否则全局安装 Claude Code 时会出现权限错误，Windows 上表现为需要管理员权限，Ubuntu 上表现为 EACCES 报错。

2.2 tmux 解决的是“会话持久化”问题

tmux 在 openrig 体系里的角色，是保证 AI 编程会话不因为终端关闭或网络抖动而中断。你可以把它理解成一个“终端里的虚拟机”——每个 tmux 窗口是一个独立的 shell 会话，detach 之后会话继续在后台跑，reattach 回来一切照旧。

为什么 AI 编程特别需要 tmux？因为 Claude Code 和 Codex 在执行任务时，往往会跑很长时间。比如你让它重构一个模块，它可能要读几十个文件、跑测试、反复修改，整个过程持续十几分钟甚至更久。如果这时候你的 SSH 断了，或者你不小心关了终端窗口，没有 tmux 的话，这个会话就没了，之前的工作上下文也丢了。有了 tmux，你 detach 之后去干别的事，回来 attach 继续看结果。

openrig 对 tmux 的编排通常体现在：自动创建命名会话（比如openrig-claude、openrig-codex）、在会话内预设好工作目录和环境变量、支持一键 attach 到指定会话。这样你就不用手动敲tmux new -s xxx再cd到项目目录了。

2.3 Claude Code 与 Codex 的定位差异

这两个工具虽然都是 AI 编程助手，但使用体验和配置方式有区别。Claude Code 更偏向“对话式编程”，你在终端里跟它聊天，它帮你改代码、跑命令、解释逻辑。Codex CLI 则更偏向“任务式执行”，你给它一个明确的任务描述，它去执行并返回结果。

在 openrig 的编排里，这两个工具通常被当作可切换的“后端”。你可以根据任务类型选择用哪个：需要深度讨论架构时用 Claude Code，需要批量执行明确任务时用 Codex。配置上的关键差异在于环境变量和认证方式，Claude Code 需要设置 API Key 或者登录订阅账号，Codex 同样需要配置对应的认证信息。openrig 的价值就在于把这些差异封装起来，让你切换时不用手动改一堆配置。

3. 实操部署：从裸机到可用的 openrig 环境

3.1 Ubuntu 下的完整安装流程

先装 Node.js。我习惯用 NodeSource 的源，命令如下：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs node -v npm -v

确认版本输出正常后，安装 Claude Code 和 Codex CLI：

npm install -g @anthropic-ai/claude-code npm install -g @openai/codex

这里有个坑：如果你之前用 sudo 装过 npm 包，可能会遇到全局包路径混乱的问题。检查一下which claude和which codex的输出，如果指向/usr/local/bin而你的 npm prefix 在~/.npm-global，说明路径不一致，需要清理旧包重新装。

接下来装 tmux：

sudo apt-get install -y tmux

然后创建 openrig 的工作目录结构。我一般会在~/openrig下放几个东西：configs/存各工具的配置文件，scripts/存启动脚本，logs/存会话日志。启动脚本的核心逻辑是：检查 tmux 会话是否存在，不存在就创建并执行 AI 工具，存在就直接 attach。

#!/bin/bash SESSION="openrig-claude" if ! tmux has-session -t $SESSION 2>/dev/null; then tmux new-session -d -s $SESSION -c ~/projects tmux send-keys -t $SESSION "claude" C-m fi tmux attach -t $SESSION

这个脚本虽然简单，但解决了 80% 的日常需求。你可以把它保存为~/openrig/scripts/start-claude.sh，加个 alias 就能随时调用。

3.2 Windows 下的注意事项

Windows 上跑这套东西，最大的障碍是终端环境。原生 CMD 和 PowerShell 对 tmux 的支持几乎为零，所以你需要 WSL2。在 WSL2 的 Ubuntu 环境里，上面的步骤完全适用。如果你坚持用原生 Windows，那 tmux 这一环就得换成 Windows Terminal 的多标签页加后台进程方案，但会话持久化能力会打折扣。

Claude Code 在 Windows 上有桌面版和 VS Code 插件版，热搜词里 “claude code windows” 和 “claude code for vs code” 出现频率很高。我的建议是：如果你主要用 VS Code 写代码，直接装 Claude Code 的 VS Code 插件，体验比终端版更顺滑。但如果你需要 tmux 的会话管理能力，还是得回到 WSL2 里用 CLI 版本。

Codex 在 Windows 上的安装相对直接，npm 全局安装后就能用。但要注意 Windows 的路径分隔符和换行符问题，有时候 Codex 读取配置文件时会因为 CRLF 报错，用dos2unix转一下就好。

3.3 本地模型接入的配置要点

热搜词里 “claude code 调用 lmstudio 的本地模型” 和 “codex 接入 deepseek” 说明很多人想用本地或第三方模型来驱动这些 AI 编程工具。这个需求是合理的：本地模型没有网络延迟，数据不出本机，成本也可控。

以 LM Studio 为例，它启动后会在本地开一个兼容 OpenAI 接口的服务，默认地址是http://localhost:1234/v1。你要做的是把 Claude Code 或 Codex 的 API Base URL 指向这个地址，并把 API Key 设成任意非空字符串（LM Studio 不校验 Key）。具体配置方式取决于工具，Claude Code 通过环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY来控制，Codex 则通过OPENAI_BASE_URL和OPENAI_API_KEY。

注意：本地模型的上下文窗口通常比云端模型小，Claude Code 在处理大项目时可能会因为上下文超限而报错。这时候需要在配置里调小max_tokens或者限制它读取的文件数量。

4. 模型切换与代理配置的实战经验

4.1 多模型供应商切换的痛点

热搜词里 “cc switch local proxy failed while handling codex endpoint /responses” 这个报错，暴露了一个典型问题：当你用中间层代理来切换模型供应商时，不同工具的 API 路径格式不一致，代理层可能无法正确转发。

Claude Code 用的是 Anthropic 的 Messages API 格式，Codex 用的是 OpenAI 的 Responses API 格式。如果你用一个统一的代理来转发请求，就必须在代理层做格式转换。很多轻量级代理工具只做了简单的 URL 转发，没有做请求体格式适配，结果就是 Codex 的请求发到 Anthropic 格式的端点上报错。

我的解决方案是：不要用一个代理硬扛所有工具，而是给每个工具配独立的 Base URL。Claude Code 指向支持 Anthropic 格式的端点，Codex 指向支持 OpenAI 格式的端点。如果两个工具要用同一个模型供应商，先确认该供应商是否同时提供两种格式的兼容接口。大多数主流供应商现在都提供 OpenAI 兼容接口，但 Anthropic 原生格式的支持参差不齐。

4.2 代理配置的排查清单

当你遇到 “local proxy failed” 这类报错时，按以下顺序排查：

排查项检查方法常见问题
代理进程是否存活curl http://localhost:端口/health进程崩溃或端口被占用
Base URL 是否正确检查环境变量输出多了或少了/v1路径
API Key 是否有效用 curl 直接请求测试Key 过期或额度耗尽
请求格式是否匹配查看代理日志中的请求体Anthropic 格式发到了 OpenAI 端点
网络是否可达curl -v看连接过程DNS 解析失败或连接超时

这个表格里的每一项我都实际踩过坑。最隐蔽的是 Base URL 路径问题：有些供应商的端点是https://api.example.com/v1，有些是https://api.example.com，差一个/v1就会导致 404。我的习惯是先用 curl 手动测通一个最简单的请求，确认端点、Key、格式都对了，再写进配置文件。

4.3 环境变量管理的最佳实践

openrig 环境里会涉及大量环境变量：API Key、Base URL、模型名称、超时时间、代理设置等。如果全部写在.bashrc里，会越来越乱，而且不同项目可能需要不同的配置。

我的做法是用 direnv 或者简单的 shell 脚本做环境隔离。每个项目目录下放一个.envrc或env.sh，进入目录时自动加载对应的环境变量。openrig 的启动脚本会先 source 这个文件，再启动 AI 工具。这样切换项目时，模型配置也跟着切换，不会串。

# ~/projects/myapp/env.sh export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="local-model" export ANTHROPIC_MODEL="qwen2.5-coder-32b"

这个文件不要提交到 Git，加到.gitignore里。团队协作时，可以提供一个env.sh.example作为模板。

5. 常见报错与排查技巧实录

5.1 安装类报错

“error installing 24.21.0: node.js v24.21.0 is not yet released” 这个报错的原因很直接：你指定的 Node.js 版本号不存在。Node.js 的版本号是严格递增的，24.21.0 可能还没发布，或者你记错了版本号。解决办法是去 Node.js 官网看当前 LTS 版本号，或者直接用nvm install --lts让工具自己选。

另一个常见问题是 npm 全局安装时的权限错误。Ubuntu 上表现为EACCES: permission denied，Windows 上表现为需要管理员权限。根本原因是 npm 的全局目录设在了系统路径下。修复方法是重新配置 npm prefix 到用户目录：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

然后重新安装 Claude Code 和 Codex。

5.2 认证与订阅类报错

“your organization has disabled claude subscription access for claude code” 这个报错说明你的账号所属组织禁用了 Claude Code 的订阅访问。如果你用的是公司账号，需要联系管理员开通权限。如果是个人账号，检查一下订阅状态是否正常。

“codex 无法加载组织设置” 通常是配置文件路径问题。Codex 会在用户目录下找配置文件，如果文件不存在或格式错误，就会报这个错。检查~/.codex/config.json或对应的配置文件是否存在，JSON 格式是否合法。

5.3 运行时类报错

“codex is ignoring 1 unrecognized configuration setting” 这是一个警告而非错误，意思是配置文件里有一个 Codex 不认识的配置项。不影响使用，但建议清理掉，避免以后混淆。用codex config list可以查看当前生效的配置项。

“claude code might not be available in your country” 这个提示说明当前网络环境可能无法直连 Anthropic 的服务。如果你用的是本地模型或第三方兼容端点，这个提示可以忽略，因为请求根本没发到 Anthropic 的服务器。如果确实需要用官方服务，检查网络连通性。

5.4 会话管理类问题

tmux 会话丢失是最常见的问题。原因通常是机器重启或者 tmux 进程被杀死。openrig 的启动脚本应该包含“会话不存在则创建”的逻辑，这样即使会话丢了，重新运行脚本就能恢复。但之前会话里的上下文（比如 Claude Code 的对话历史）可能无法恢复，这取决于工具本身是否持久化对话记录。

另一个问题是 tmux 里的环境变量不生效。这是因为 tmux 启动新会话时，加载的是登录 shell 的环境，而不是你当前 shell 的环境。解决办法是在启动脚本里显式 source 环境文件，或者用tmux send-keys在会话内执行 export 命令。

6. 进阶玩法：把 openrig 变成团队协作工具

6.1 共享会话与结对编程

tmux 支持多客户端 attach 到同一个会话，这意味着两个人可以同时看到同一个 AI 编程会话的输出。对于结对编程场景，这个功能很实用：一个人操作 AI，另一个人在旁边看结果并讨论。

具体做法是：在服务器上创建 tmux 会话并启动 Claude Code，然后两个人分别 SSH 到服务器，执行tmux attach -t openrig-claude。两个人的终端会同步显示相同的内容，输入也会互相可见。注意要设置好窗口大小同步，否则小窗口那边会显示错乱。在 tmux 里按Ctrl+b然后:setw synchronize-panes on可以同步窗格。

6.2 日志记录与回放

openrig 的会话日志对于排查问题和复盘很有价值。tmux 本身支持 pipe-pane 功能，可以把会话输出重定向到文件：

tmux pipe-pane -t openrig-claude -o 'cat >> ~/openrig/logs/claude-$(date +%Y%m%d).log'

这样所有输出都会追加到日志文件里。配合script命令或者 asciinema，还能记录完整的终端操作回放。我一般会保留最近一周的日志，出问题时翻日志比凭记忆靠谱得多。

6.3 自动化任务编排

openrig 的终极形态是自动化：定时拉取代码、自动跑 AI 代码审查、自动生成提交信息。这些都可以通过 tmux 加 shell 脚本实现。比如每天早上 9 点自动启动一个 Codex 会话，让它检查昨晚的 CI 结果并生成报告。

# 在 crontab 里添加 0 9 * * * ~/openrig/scripts/morning-check.sh

morning-check.sh的内容是创建 tmux 会话、启动 Codex、发送预设的任务描述、把结果输出到文件。这样你到公司打开电脑，报告已经生成好了。

注意：自动化任务里不要用需要交互式认证的工具，否则会卡在登录步骤。确保 API Key 已经配置在环境变量里，并且有足够的额度。

7. 我踩过的坑与最终稳定方案

折腾 openrig 这套环境大概花了两个周末，踩的坑主要集中在三个地方。

第一个坑是 Node.js 版本混乱。一开始我用系统自带的 Node.js，版本太老，Claude Code 装不上。后来用 nvm 装了最新版，结果 Codex 又跟最新版有兼容问题。最后锁定在 Node.js 22 LTS，两个工具都正常。所以我的建议很明确：别追新，用 LTS。

第二个坑是代理配置。我一开始想用一个代理同时服务 Claude Code 和 Codex，结果就是热搜词里那个 “local proxy failed” 报错。折腾了半天才想明白，两个工具的 API 格式根本不一样，一个代理扛不住。后来改成每个工具独立配置 Base URL，问题消失。这个教训是：不要为了省事而强行统一，该分开就分开。

第三个坑是 tmux 会话的环境变量。我在.bashrc里配了 API Key，但 tmux 会话里死活读不到。后来发现 tmux 启动的是非登录 shell，不加载.bashrc。解决办法是在启动脚本里显式 source 环境文件，或者用tmux new-session -d -s xxx 'source ~/.bashrc && claude'这种方式。

最终稳定下来的方案是：Ubuntu 服务器上跑 tmux，Node.js 22 LTS，Claude Code 和 Codex 各自独立配置，环境变量通过项目目录下的env.sh管理，启动脚本放在~/openrig/scripts/下，日志保留一周。这套方案跑了三个月，没再出过大的问题。

如果你刚开始搭这套环境，我的建议是从最简单的开始：先装 Node.js 和 tmux，再装一个 AI 工具（Claude Code 或 Codex 选一个），跑通之后再考虑加第二个工具和本地模型。不要一上来就追求全功能，那样容易在配置环节卡住，打击积极性。先把一个工具用顺了，再逐步扩展，这样每一步都有正反馈。