企业官网建设流程全解析

1. 从 openrig 说起：一个把 Claude Code 和 Codex 装进同一副骨架的思路

第一次看到 openrig 这个名字，我下意识把它拆成了 open 和 rig 两截。rig 在工程语境里是“装配架、机架”的意思，比如测试台架、摄像机机架。所以 openrig 直译过来就是“开放的装配架”。结合它周边冒出来的 Claude Code、Codex、Node.js、tmux 这几个热搜词，我基本能判断出它想干的事：把当下最主流的两个终端 AI 编程助手，塞进一个统一、可复用、可切换的运行骨架里，让它们共享同一套环境、同一套会话管理、同一套模型接入方式。

这个判断不是拍脑袋。你去看那串热词就明白了：claude code 安装、codex 安装、node.js 安装、tmux、cc switch local proxy failed、codex 接入 deepseek、claude code 调用 lmstudio 的本地模型、vscode 配置 claude code……这些词几乎覆盖了一个开发者从零开始搭建 AI 编程环境的完整链路。而 openrig 要解决的，正是这条链路里最烦人的部分——环境割裂。

我自己的经历很典型。最开始我单独装 Claude Code，跑通了；后来想试试 Codex，又单独装一遍，结果两套 Node.js 版本要求不一样，两套配置目录互相打架，tmux 会话里切来切去经常搞混哪个窗口跑的是哪个工具。更别提模型接入，Claude Code 走一套 API 配置，Codex 走另一套，想同时接本地模型和云端模型，配置文件能写到你怀疑人生。openrig 这类项目的价值就在这儿：它不发明新模型，也不重写 AI 能力，它做的是“机架”——把工具、运行时、会话、模型接入这几层标准化地装配起来。

所以这篇内容适合谁看？如果你只是偶尔用用网页版 AI 聊天，那可以先收藏着；但如果你已经或准备把 Claude Code、Codex 这类终端助手当成日常主力开发工具，尤其是需要在 Windows、Ubuntu、VS Code 之间来回切换，还想接本地模型或第三方 API，那 openrig 这套思路值得你花时间吃透。下面我会从整体设计、核心细节、实操落地、问题排查四个层面，把这件事讲清楚，尽量让你看完就能自己搭一套。

2. openrig 的整体设计与思路拆解

2.1 为什么需要一层“机架”而不是各装各的

先说一个很多人踩过的坑：以为 Claude Code 和 Codex 是两个互不相干的工具，各装各的最省事。短期看确实如此，长期看是灾难。原因有三层。

第一层是运行时冲突。Claude Code 和 Codex 都是基于 Node.js 生态的命令行工具，但它们对 Node.js 版本的要求经常不一致。热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是活生生的例子——你照着某个教程去装一个还不存在的版本，直接报错。如果你全局只装一个 Node.js，两个工具可能有一个跑不起来；如果你装多个版本，又得靠 nvm 之类的版本管理器来回切，切错了就是各种玄学报错。

第二层是配置目录污染。这两个工具默认都会在用户主目录下建自己的配置文件夹，里面存 API key、模型端点、会话历史、权限设置。你手动改来改去，很容易出现“我明明改了配置但工具不生效”的情况，因为可能改的是旧版本残留的目录，或者被环境变量覆盖了。热词里codex is ignoring 1 unrecognized configuration setting. check for typos or d就是配置写错但工具只是警告不报错的典型，排查起来很费劲。

第三层是会话管理割裂。终端 AI 助手最爽的用法是长时间挂着会话，边写代码边对话。tmux 就是干这个的。但如果你 Claude Code 开一个 tmux 窗口，Codex 开另一个，模型切换、上下文同步、日志查看全得手动来。openrig 的思路是把这些统一到一层“机架”上：运行时用统一的 Node.js 版本策略，配置用统一的目录结构和环境变量注入，会话用 tmux 统一编排，模型接入用统一的代理层。

提示：这里的“统一”不是强制所有工具用同一个配置，而是提供一套标准化的装配规则，让每个工具在规则内各取所需，互不干扰。

2.2 核心分层：运行时层、工具层、会话层、模型层

把 openrig 拆开看，我习惯分成四层，这个分层也决定了你后面实操时该先动哪一层。

运行时层负责 Node.js 和包管理器。这是地基。我的建议是永远不要用系统自带的 Node.js，而是用版本管理器（nvm 或 fnm）装一个 LTS 版本，再为特殊工具准备一个独立版本。热词里node.js lts下载、安装node.js、node.js是干什么的说明很多人卡在这一步。Node.js 本质是让 JavaScript 能在浏览器外运行的运行时，这些 AI 命令行工具都是用它写的，所以它是前置依赖，绕不开。

工具层就是 Claude Code 和 Codex 本体，以及它们的安装方式。这里有个关键选择：全局安装还是项目内安装。全局安装方便，但版本冲突风险高；项目内安装隔离好，但每个项目都要装一遍。openrig 这类机架通常倾向于用统一的安装脚本，把工具装到一个受控的全局位置，同时用包装脚本（wrapper）来注入环境变量。

会话层是 tmux。tmux 是终端复用器，简单说就是让你在一个终端窗口里开多个“窗格”和“窗口”，并且断开连接后会话还在后台跑。对于 AI 编程助手，这意味着你可以让 Claude Code 在一个窗格里持续工作，自己在另一个窗格看日志或跑测试，关掉终端再回来，会话还在。热词里 tmux 反复出现，说明这是刚需。

模型层是最容易出问题的一层。Claude Code 默认接 Anthropic 的模型，Codex 默认接 OpenAI 的模型，但大家都想接第三方或本地模型。热词里claude code 调用lmstudio的本地模型、codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型全是这个诉求。openrig 的思路是提供一个本地代理层，把不同工具的请求格式统一转换后转发到目标模型端点。热词里cc switch local proxy failed while handling codex endpoint /responses就是代理层出问题的典型报错，后面我会专门讲怎么排查。

2.3 方案选型背后的取舍逻辑

为什么用 tmux 而不是 VS Code 内置终端？因为 VS Code 终端是依附于编辑器进程的，关掉编辑器会话就没了，而且多窗口管理不如 tmux 灵活。tmux 是独立进程，可以 SSH 上去接着用，这对远程开发场景是刚需。热词里ubuntu配置claude code、ubuntu 安装claude code说明不少人在 Linux 服务器上跑，tmux 几乎是标配。

为什么强调 Node.js 版本管理而不是直接装最新版？因为 AI 工具更新快，今天要求 Node 18，明天可能要求 Node 20，后天某个依赖又只兼容 Node 22。用版本管理器可以随时切换，不用卸载重装。热词里那个24.21.0 is not yet released的报错，本质就是版本号写错了或者源里还没有，用版本管理器就能清楚看到哪些版本真实可用。

为什么模型接入要走本地代理而不是直接改工具配置？因为每个工具的配置格式、认证方式、请求路径都不一样。直接改配置，一旦工具升级配置格式变了，你又得重来。本地代理层相当于一个适配器，工具那边配置不变，代理层负责翻译。代价是多了一个进程要维护，但换来的是灵活性和可维护性。

3. 核心细节解析与实操要点

3.1 Node.js 运行时：版本选择与安装避坑

Node.js 这块我先给结论：用 nvm（Linux/macOS）或 fnm（跨平台，Windows 也友好）装一个 LTS 版本作为默认，再按需装其他版本。不要用官网下载的安装包直接覆盖系统 Node，也不要盲目追最新版。

具体操作上，Linux 和 macOS 下装 nvm 就是一行脚本的事，装完nvm install --lts拿到当前 LTS，nvm alias default lts/*设为默认。Windows 下我更推荐 fnm，因为它对 PowerShell 支持好，安装也简单。装完之后用node -v和npm -v验证。

这里有个细节很多人忽略：npm 的全局包安装路径。如果你切换了 Node 版本，之前全局装的 Claude Code 或 Codex 可能就找不到了，因为全局包是跟着 Node 版本走的。解决办法是要么每个版本都重装一遍工具，要么用npm config set prefix把全局路径固定到一个与版本无关的目录。我一般选后者，这样切版本不影响工具可用性。

注意：热词里error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错，九成是版本号写错或镜像源没同步。先用nvm ls-remote看看真实可用的版本列表，别照着来路不明的教程硬填版本号。

3.2 Claude Code 与 Codex 的安装与共存

Claude Code 和 Codex 的安装方式类似，都是通过 npm 全局安装对应的包。安装本身不难，难的是让它们共存且不互相干扰。

我的做法是给每个工具建独立的配置目录，通过环境变量指定。比如 Claude Code 用CLAUDE_CONFIG_DIR指向~/.config/openrig/claude，Codex 用对应的环境变量指向~/.config/openrig/codex。这样两个工具的配置、缓存、会话历史完全隔离，升级或卸载一个不会影响另一个。

安装顺序上，先确保 Node.js 就绪，再装 Claude Code，验证能启动，再装 Codex，再验证。不要两个一起装，出问题不好定位。验证的方式很简单，跑一下工具的版本命令或帮助命令，能正常输出就说明安装成功。

热词里claude code安装、codex安装、codex安装 windows桌面版、codex安装 csdn说明安装教程满天飞，但质量参差不齐。我的建议是优先看官方文档，热词里claude code官方文档链接就是干这个的。第三方教程可以参考，但版本号和命令要以官方为准，因为工具更新太快，半年前的教程可能已经失效。

3.3 tmux 会话编排：让 AI 助手常驻后台

tmux 的用法不复杂，但要用好需要一点设计。我的基本配置是：一个 session 叫ai，里面开三个 window。window 0 跑 Claude Code，window 1 跑 Codex，window 2 用来跑测试、看日志、执行 git 命令。每个 window 可以再分 pane，比如 window 0 左边跑 Claude Code，右边跑一个 tail 日志的命令。

这样设计的好处是，你 SSH 到服务器上，tmux attach -t ai一下，所有 AI 会话原封不动还在。关掉本地终端，服务器上的会话继续跑。对于长时间让 AI 改代码、跑重构的场景，这个体验是质的提升。

tmux 配置上我建议改几个默认键位，比如把前缀键从Ctrl+b改成Ctrl+a，因为Ctrl+b在很多终端里和光标移动冲突。再开鼠标支持，方便滚动和选择窗格。这些配置写在~/.tmux.conf里，一次配置长期受益。

提示：tmux 会话里的环境变量是启动时继承的。如果你在会话启动后才改了 Node.js 版本或配置目录，记得重启会话或手动 source 一下，否则工具读到的还是旧环境。

3.4 模型接入层：本地代理与第三方 API 的配置要点

模型接入是 openrig 这套体系里最灵活也最容易翻车的部分。核心思路是：工具只认一个本地端点，本地代理负责把请求转发到真正的模型服务。

以 Claude Code 接本地模型为例，你需要一个兼容 Anthropic 请求格式的代理，把请求转成目标模型能懂的格式。Codex 接第三方模型同理，需要一个兼容 OpenAI 请求格式的代理。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错，说明代理在处理 Codex 的/responses端点时失败了，可能原因是代理版本不支持这个端点，或者请求格式转换有 bug。

排查这类问题的顺序是：先确认代理进程在跑，再确认工具配置的端点地址和代理监听地址一致，然后用 curl 手动打一下代理端点看返回什么。如果 curl 能通但工具不通，那就是工具配置问题；如果 curl 也不通，那就是代理本身的问题。热词里codex无法加载组织设置、your organization has disabled claude subscription access for claude code这类报错，多半是账号权限或订阅状态问题，和代理无关，要分开排查。

4. 实操过程与核心环节实现

4.1 从零搭建：环境准备与依赖安装

假设你是一台干净的 Ubuntu 机器，我们从零走一遍。第一步装基础工具：sudo apt update && sudo apt install -y curl git tmux build-essential。这几样是后续所有操作的前提，curl 用来下载，git 用来拉代码，tmux 用来管会话，build-essential 用来编译某些 npm 原生依赖。

第二步装 Node.js 版本管理器。以 nvm 为例，用官方脚本安装，装完 source 一下 shell 配置，然后nvm install --lts。装完验证node -v，应该输出一个 LTS 版本号。如果输出的是系统自带的老版本，说明 nvm 没生效，检查 shell 配置里有没有正确加载 nvm。

第三步配置 npm 全局路径。npm config set prefix ~/.npm-global，然后把~/.npm-global/bin加到 PATH 里。这一步是为了让全局安装的工具不随 Node 版本切换而丢失。做完之后npm config get prefix确认一下。

第四步装 Claude Code 和 Codex。用 npm 全局安装对应的包，装完分别跑版本命令验证。如果某个工具报找不到命令，检查 PATH 和全局路径配置。

4.2 配置隔离：让两个工具各用各的配置目录

环境就绪后，建配置目录结构。我一般这样组织：

mkdir -p ~/.config/openrig/claude mkdir -p ~/.config/openrig/codex mkdir -p ~/.config/openrig/logs

然后在 shell 配置里加环境变量，把两个工具的配置目录分别指过去。具体变量名以各工具官方文档为准，因为工具版本不同变量名可能有差异。加完之后重新加载 shell 配置，再启动工具，确认配置写到了新目录而不是默认目录。

这一步的验证方法是：启动工具后随便改一个配置项，然后去对应目录看文件有没有更新。如果更新在默认目录而不是你指定的目录，说明环境变量没生效，检查变量名拼写和加载顺序。

注意：环境变量的加载顺序很重要。如果你在.bashrc和.profile里都写了，可能互相覆盖。建议只在一个地方写，并且确保非交互式 shell 也能加载到，否则 tmux 里启动的工具可能读不到。

4.3 tmux 编排：一键拉起整套 AI 工作台

配置隔离做完，就可以用 tmux 把整套工作台串起来。我写了一个启动脚本，逻辑是：检查是否已有ai会话，有就 attach，没有就新建并配置好窗口和窗格。

脚本核心命令大概是：tmux new-session -d -s ai -n claude建会话和第一个窗口，然后tmux new-window -t ai -n codex建第二个窗口，tmux new-window -t ai -n shell建第三个。再往窗口里发命令，比如tmux send-keys -t ai:claude 'claude' Enter。

这样每次开工，跑一下脚本，三个窗口就绪，Claude Code 和 Codex 各自在自己的窗口里跑，互不干扰。需要看日志或跑命令就切到 shell 窗口。关掉终端再回来，tmux attach -t ai一切照旧。

脚本里我还会加一些健壮性检查，比如 Node.js 版本对不对、工具在不在 PATH 里、配置目录存不存在。任何一项不满足就打印提示并退出，避免带着错误环境启动。

4.4 模型接入实操：以接本地模型为例

接本地模型这块，假设你本地已经跑了一个兼容 OpenAI 或 Anthropic 格式的模型服务。第一步确认模型服务的地址和端口，比如http://127.0.0.1:1234。第二步启动本地代理，把代理的监听地址配成工具要访问的地址，把上游地址配成模型服务地址。

代理启动后，用 curl 验证：curl http://127.0.0.1:代理端口/v1/models看能不能列出模型。能列出说明代理到模型服务这段通了。然后配置工具，把 API base 指向代理地址，API key 随便填一个（本地代理通常不校验），模型名填代理支持的模型名。

启动工具，发一条简单消息，看能不能正常返回。如果报错，看代理日志，日志里会显示请求转发到了哪里、返回了什么。热词里claude code 调用lmstudio的本地模型这类场景，关键就是代理要正确转换请求格式，因为 LM Studio 的接口格式和 Anthropic 的不完全一样。

提示：本地模型服务通常对并发和上下文长度有限制。如果你在 tmux 里同时跑 Claude Code 和 Codex 都接同一个本地模型，可能会互相抢资源。建议错开使用，或者给每个工具配不同的模型实例。

5. 常见问题与排查技巧实录

5.1 安装类问题速查

安装阶段的问题最集中，我整理了一张速查表，覆盖热词里出现的高频报错。

这张表里的每一条我都实际遇到过。尤其是版本号那条，很多人照着博客里的命令直接复制，博客写的时候那个版本存在，等你看到的时候可能已经被撤了或者还没发布。养成先查可用版本再安装的习惯，能省很多时间。

5.2 配置类问题排查思路

配置类问题的典型表现是“改了不生效”或“工具忽略了某个设置”。热词里codex is ignoring 1 unrecognized configuration setting就是工具读到了配置但不认识，只是警告不报错。这种情况要去看工具的配置文档，确认字段名和格式。

排查配置问题的通用思路是：先确认工具读的是哪个配置文件，再确认文件内容格式正确，最后确认没有环境变量覆盖。很多工具支持--verbose或--debug之类的参数，启动时加上能看到它实际加载了哪些配置。如果工具没有这个参数，就去看它的日志文件，通常在配置目录下的 logs 子目录里。

还有一个常见坑是配置文件的格式。有的工具用 JSON，有的用 YAML，有的用 TOML。JSON 里多一个逗号、YAML 里缩进错一格，都可能导致整个配置被忽略。改完配置用工具自带的校验命令或在线校验器过一遍，能避免大部分低级错误。

5.3 代理与模型接入问题实录

代理层的问题最隐蔽，因为涉及工具、代理、模型服务三个环节。热词里cc switch local proxy failed while handling codex endpoint /responses这个报错，我的排查顺序是这样的。

先看代理进程是否存活，ps aux | grep 代理名确认。再看代理监听的端口是否和工具配置的一致，ss -tlnp | grep 端口确认。然后用 curl 直接打代理端点，看返回什么。如果 curl 返回 404，说明代理没实现这个端点，需要升级代理或换一个支持该端点的代理。如果 curl 返回 500，看代理日志里的堆栈，通常是请求格式转换失败。

工具侧的问题，重点看 API base 配置和认证配置。有的工具要求 API base 带/v1，有的不带，配错了就是 404。认证方面，本地代理通常不校验 key，但工具可能强制要求填，随便填一个非空字符串即可。如果工具报认证失败，先确认代理是否真的不校验，再确认 key 有没有被 shell 转义搞坏。

5.4 会话与 tmux 问题排查

tmux 相关的问题主要是会话丢失、窗格错乱、环境变量不对。会话丢失通常是机器重启或 tmux 进程被杀，这个没办法，只能重新拉起。窗格错乱多半是误触了快捷键，tmux kill-session重来最快。环境变量不对是启动顺序问题，前面提过，重启会话或手动 source 即可。

还有一个容易被忽略的点是 tmux 里的终端类型。有的 AI 工具会根据终端类型决定是否启用彩色输出或交互模式。如果 tmux 里工具行为异常，检查echo $TERM，正常应该是screen或tmux-256color。如果是dumb，说明终端类型没设对，在 tmux 配置里加上set -g default-terminal "tmux-256color"能解决。

6. 我踩过的坑和几条实在建议

先说一个最坑的：不要在生产环境的系统 Node 上直接装这些工具。我有一次在一台服务器上图省事，直接用系统 Node 装了 Claude Code，结果后来系统更新把 Node 升级了，工具直接跑不起来，排查了半天才发现是版本问题。从那以后我所有机器都用版本管理器，系统 Node 只用来跑系统脚本，绝不碰。

第二个坑是配置文件乱放。早期我没做配置隔离，两个工具的配置混在一个目录里，改 A 的时候不小心动了 B 的字段，结果 B 启动就报错。后来严格按工具分目录，每个工具的环境变量在启动脚本里显式注入，再没出过这类问题。

第三个坑是代理层版本不匹配。工具升级后请求格式变了，代理还是老版本，就会出现local proxy failed这类报错。我的做法是代理和工具一起升级，升级前先看两者的兼容性说明。如果代理项目更新不活跃，就换一个活跃的替代品，别硬扛。

最后给几条实在建议。第一，所有配置和脚本都进 git，换机器时 clone 下来就能用，比手动配快十倍。第二，tmux 会话名和窗口名起得有意义，别用默认的 0、1、2，时间长了根本记不住哪个是哪个。第三，模型接入先跑通最简单的云端模型，再折腾本地模型和第三方 API，一步步来，别一上来就搞最复杂的组合。第四，遇到报错先看日志，工具的日志、代理的日志、模型服务的日志，三个都看，大部分问题日志里写得清清楚楚，比在网上搜半天快得多。

这套 openrig 思路的核心不是某个具体工具，而是“分层装配、配置隔离、会话常驻、接入统一”这十六个字。你把这四件事做到位，不管以后换什么 AI 编程助手，都能快速接进来，不用每次都从零折腾环境。