企业官网建设流程全解析

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

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟“rig”在英文里常指设备支架或矿机机架。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编程助手，大概率已经在某个 issue 或讨论帖里见过它。openrig 本质上是一个面向 AI 编程 CLI 工具的本地运行编排层，它把 Node.js 运行时、tmux 会话管理、多模型接入配置这几件琐碎但容易出错的事情，收敛成一套可复现的启动流程。

我最初接触它是因为一个很具体的痛点：在 Ubuntu 服务器上同时跑 Claude Code 和 Codex，每次重连 SSH 之后会话就断了，重新配置环境变量、切换 API 端点、确认 Node 版本，一套流程走下来十几分钟就没了。更麻烦的是，Claude Code 和 Codex 对 Node.js 版本的要求并不完全一致，全局装一个版本经常顾此失彼。openrig 出现的意义就在于，它不试图替代这些工具，而是给它们提供一个稳定的“底座”。

它适合谁？三类人最值得关注。第一类是经常在远程服务器上使用 AI 编程助手的开发者，tmux 会话保持是刚需；第二类是需要在本机同时管理多个模型端点的人，比如白天用云端模型、晚上切到 LM Studio 本地模型；第三类是刚入门 Claude Code 或 Codex 的新手，面对 Node.js 安装、环境变量配置、组织权限报错这些坑，openrig 能帮你跳过大量试错。

需要说明的是，openrig 目前并不是一个官方发布的大型框架，更多是社区实践中沉淀出来的一套编排思路和配套脚本。所以下面讲的内容，一部分来自项目本身的定位，一部分是我在实际搭建过程中基于常见实践补全的细节，你在复现时可以根据自己的环境做调整。

2. 核心设计思路：为什么是 Node.js + tmux 这套组合

2.1 Node.js 版本管理是整个链条的地基

Claude Code 和 Codex 的 CLI 都是 Node.js 生态的产物，这一点决定了你的运行环境必须有一个可用的 Node.js。热搜词里频繁出现“node.js安装”“node.js官网下载”“node.js lts下载”“error installing 24.21.0: node.js v24.21.0 is not yet released”，说明大量用户在版本选择上栽过跟头。

我的建议很明确：不要追最新版，锁定 LTS。Node.js 的奇数版本是实验性的，偶数版本才是长期支持。比如 v20 和 v22 都是 LTS，而 v24 在某个时间点可能还没正式发布，你如果照着某个教程敲了nvm install 24.21.0，就会直接撞上“is not yet released”的报错。openrig 的思路是把 Node 版本写进配置，用 nvm 或 fnm 做版本切换，而不是依赖系统全局的那一个。

为什么不用系统自带的 Node？因为 Ubuntu 的 apt 源里的 Node 版本往往偏旧，而 Claude Code 这类工具更新频繁，旧版本可能在某个版本之后就不再兼容。用版本管理器还有一个好处：你可以给 Claude Code 和 Codex 分别指定不同的 Node 版本，互不干扰。

2.2 tmux 解决的是“会话存活”这个隐形需求

很多人第一次用 Claude Code 是在本地终端里，关掉窗口任务就没了。但一旦你把它放到远程服务器上，SSH 断线就意味着进程被杀。tmux 在这里扮演的角色是会话容器：你在 tmux 里启动 Claude Code，即使 SSH 断开，进程依然在服务器上跑着，下次连上去tmux attach就能接着看。

openrig 把 tmux 纳入核心设计，还有一个更细的考量：Claude Code 支持直接执行终端命令，Codex 也有类似的交互能力。如果你让它们在裸终端里跑，一个误操作可能影响整个 shell 环境。放进 tmux 的独立窗口或面板里，相当于给每个 AI 助手划了一块“自留地”，出问题只影响那个 pane，不会波及你的主工作环境。

2.3 多端点切换是绕不开的现实需求

热搜词里“cc switch local proxy failed while handling codex endpoint /responses”“使用cc switch 接入 deepseek v4, qwen, glm等模型”“codex接入deepseek”这些，反映的是一个普遍场景：用户不想只绑死在一个模型上。Claude Code 默认走 Anthropic 的端点，Codex 默认走 OpenAI 的端点，但实际使用中，你可能因为成本、速度、可用性等原因，需要切换到 DeepSeek、Qwen、GLM 或者本地的 LM Studio。

openrig 在这方面的价值是把端点配置从工具内部抽离出来。它不修改 Claude Code 或 Codex 的源码，而是通过环境变量和配置文件，在启动时注入不同的 base URL 和 API Key。这样做的好处是切换成本极低，你不需要每次手动改配置文件，只需要在 openrig 的配置里选一个 profile。

3. 环境搭建实操：从裸机到可运行状态

3.1 Node.js 安装的三种路径与选择依据

在 Ubuntu 上装 Node.js，常见的有三条路：apt、nvm、官方二进制包。我逐一说说适用场景。

apt 最简单，sudo apt install nodejs npm两条命令搞定，但版本通常落后。如果你只是临时跑一下，不介意版本旧，可以用。但 Claude Code 和 Codex 的某些版本会检查 Node 版本号，太旧会直接拒绝启动。

nvm 是我最推荐的方式。安装命令是：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

装完之后需要重新加载 shell 配置，然后nvm install 22装 LTS 版本，nvm use 22切换。nvm 的好处是版本隔离彻底，每个项目可以用不同的 Node 版本。openrig 的配置里通常会写一个.nvmrc文件，里面就一行版本号，进入目录时nvm use自动切换。

官方二进制包适合不想装额外管理工具的人。去 Node.js 官网下载 LTS 的 Linux 二进制压缩包，解压到/usr/local或~/.local，然后把 bin 目录加进 PATH。这种方式可控性强，但升级时要手动替换。

注意：如果你在安装时看到“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”，不要慌，这不是你的问题，是这个版本号本身不存在或还没发布。换成nvm install --lts即可。

3.2 tmux 的基础配置与会话规划

tmux 安装很简单，sudo apt install tmux即可。但默认配置用起来不太顺手，我建议至少改几个地方。

在~/.tmux.conf里加上：

set -g mouse on set -g base-index 1 setw -g pane-base-index 1 set -g history-limit 10000

mouse on让你可以用鼠标切换面板和滚动，base-index 1让窗口编号从 1 开始而不是 0，符合直觉。history-limit调大是因为 Claude Code 的输出可能很长，默认的 2000 行不够翻。

会话规划上，我的习惯是给 openrig 单独开一个 session，名字叫rig。里面分三个窗口：窗口 1 跑 Claude Code，窗口 2 跑 Codex，窗口 3 留作 shell 用来查日志和改配置。这样tmux attach -t rig一进去就是完整的工作台。

3.3 Claude Code 与 Codex 的安装要点

Claude Code 的安装方式取决于你用的版本。如果是 npm 包形式，npm install -g @anthropic-ai/claude-code是常见做法。安装后第一次运行会引导你登录或配置 API Key。热搜词里“your organization has disabled claude subscription access for claude code”这个报错，通常是因为你的账号所属组织关闭了订阅访问权限，需要在组织设置里开启，或者换用 API Key 方式而非订阅登录。

Codex 的安装类似，npm install -g @openai/codex或者从官网下载安装包。Windows 用户注意，热搜词里“codex安装 windows桌面版”说明有桌面版可选，但如果你要用 openrig 这套编排，建议还是用 CLI 版本，因为 tmux 是 Linux/macOS 生态的东西，Windows 上需要 WSL 才能配合。

安装完成后，先别急着配置 openrig，单独跑一下claude --version和codex --version，确认两个工具都能正常启动。这一步是排错的基础，如果单独都跑不起来，套上 openrig 只会更难排查。

4. openrig 配置文件的写法与参数详解

4.1 配置文件结构设计

openrig 的配置我习惯用一个 YAML 文件来管理，放在~/.config/openrig/config.yaml。结构大致分三块：runtime、sessions、profiles。

runtime 块定义 Node 版本和 tmux 的基础参数。sessions 块定义要启动哪些 AI 工具、各自在哪个 tmux 窗口、启动命令是什么。profiles 块定义不同的模型端点组合，每个 profile 包含 base URL、API Key 环境变量名、以及可选的额外参数。

这样设计的原因是关注点分离。你想换模型时只改 profiles，想调整窗口布局时只改 sessions，想升级 Node 时只改 runtime。不会出现改一个地方牵连一片的情况。

4.2 端点配置的关键参数与常见坑

以接入 DeepSeek 为例，一个 profile 大概长这样：

profiles: deepseek: base_url: "https://api.deepseek.com/v1" api_key_env: "DEEPSEEK_API_KEY" model: "deepseek-chat"

这里有几个细节值得展开。base_url的结尾要不要带/v1，取决于工具的实现。Claude Code 和 Codex 对端点路径的拼接方式不同，热搜词里“cc switch local proxy failed while handling codex endpoint /responses”这个报错，很可能就是路径拼接出了问题——Codex 期望的是/responses结尾，但代理层给的是别的路径。

我的经验是：先用 curl 手动测端点。比如curl -H "Authorization: Bearer $KEY" https://api.deepseek.com/v1/models，确认能返回模型列表，再往 openrig 里填。这样能把网络问题和配置问题分开。

api_key_env用环境变量名而不是直接写 Key，是为了避免配置文件泄露。Key 放在~/.bashrc或单独的.env文件里，配置文件可以安全地提交到私有仓库。

4.3 本地模型接入的特殊处理

热搜词里“claude code 调用lmstudio的本地模型”是一个高频需求。LM Studio 默认在http://localhost:1234/v1提供 OpenAI 兼容接口。接入时要注意两点：一是 LM Studio 的模型名要和你加载的模型一致，二是本地模型的上下文窗口可能比云端小，Claude Code 如果发送超长上下文会报错。

在 openrig 里，本地模型的 profile 我会额外加一个max_tokens限制，避免请求过大。另外本地模型不需要真实的 API Key，但很多工具会检查这个字段是否存在，所以随便填一个非空字符串即可。

5. 启动流程与日常使用习惯

5.1 一键启动脚本的编写

openrig 的核心体验是“一条命令进入工作状态”。我写了一个rig-up.sh，逻辑是：检查 tmux 会话是否存在，不存在就创建；在会话里按配置启动各个工具；最后 attach 进去。

脚本的关键片段：

#!/bin/bash SESSION="rig" if ! tmux has-session -t $SESSION 2>/dev/null; then tmux new-session -d -s $SESSION -n claude tmux send-keys -t $SESSION:claude "claude" C-m tmux new-window -t $SESSION -n codex tmux send-keys -t $SESSION:codex "codex" C-m tmux new-window -t $SESSION -n shell fi tmux attach -t $SESSION

send-keys后面的C-m相当于按回车。这个脚本跑一次，三个窗口就都起来了。

5.2 日常切换与状态查看

日常使用中，最频繁的操作是切换 profile。我的做法是在 shell 窗口里放一个rig-switch函数，接受 profile 名作为参数，更新环境变量后重启对应的 tmux 窗口。这样不需要退出整个会话。

状态查看方面，tmux 的状态栏可以配置显示当前 profile 名。在~/.tmux.conf里加一行set -g status-right "#{RIG_PROFILE}"，然后在切换 profile 时用tmux set-environment更新这个变量。这样你一眼就能看到当前用的是哪个端点，避免在错误的模型上发请求。

6. 常见报错与排查手册

6.1 安装阶段的典型问题

6.2 运行阶段的端点问题

“cc switch local proxy failed while handling codex endpoint /responses”这个报错我在测试时遇到过。排查下来是代理层把 Codex 的请求转发到了错误的路径。Codex 的/responses端点和 OpenAI 标准的/chat/completions不一样，如果你的代理只处理了后者，前者就会 404。

解决方法是确认代理层是否支持 Codex 的端点格式。如果不支持，要么换一个支持的工具，要么直接用 Codex 官方端点，不走代理。

另一个常见问题是“codex无法加载组织设置”。这通常出现在企业账号场景，Codex 启动时会尝试拉取组织级配置，如果网络不通或权限不足就会卡住。临时方案是在配置里关闭组织设置加载，用个人配置覆盖。

6.3 会话与进程管理问题

tmux 会话里的进程有时候会僵死，表现为输入没反应但窗口还在。这时候不要直接 kill 整个会话，先试试Ctrl-C中断当前命令，如果不行，在 shell 窗口里ps aux | grep claude找到进程号，单独 kill 掉，然后在原窗口重新启动。

还有一种情况是 Node 进程占满内存导致 OOM。Claude Code 处理大文件时可能吃很多内存，如果服务器内存小，建议在启动命令前加NODE_OPTIONS=--max-old-space-size=2048限制堆大小，避免拖垮整台机器。

7. 我踩过的坑与实用建议

第一个坑是不要混用全局安装和 nvm。我有一次先用 apt 装了 Node，后来又用 nvm 装了一个版本，结果which node指向的路径和npm的路径不一致，装出来的 Claude Code 跑不起来。后来统一用 nvm，把 apt 的 Node 彻底卸载才干净。

第二个坑是API Key 的引号问题。在.env文件里写DEEPSEEK_API_KEY="sk-xxx"，有些加载器会把引号也当成值的一部分，导致认证失败。建议不加引号，直接DEEPSEEK_API_KEY=sk-xxx。

第三个坑是tmux 里的环境变量不会自动继承。你在.bashrc里 export 的变量，在已经运行的 tmux 会话里是看不到的。切换 profile 后需要手动tmux set-environment或者重启会话。这个我折腾了很久才搞明白。

第四个坑是本地模型的并发限制。LM Studio 默认可能只允许一个并发请求，Claude Code 如果同时发多个请求会排队甚至超时。在 LM Studio 的设置里把并发数调大，或者在使用时避免同时触发多个任务。

最后分享一个提高效率的小习惯：把常用的排查命令做成 alias，比如alias riglog='tmux capture-pane -t rig:claude -p'，这样不用 attach 进去就能看到 Claude Code 窗口的最后输出，快速判断它是不是卡住了。这个技巧在远程服务器上特别省事。