企业官网建设流程全解析

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

第一次看到 openrig 这个名字，很多人会以为是某个硬件支架或者开源机械臂项目。实际上，它跟物理世界没有半点关系，而是一套围绕 AI 编程助手做多模型编排与终端会话管理的工具链方案。简单说，openrig 要解决的核心痛点是：当你同时使用 Claude Code、Codex 这类命令行 AI 编程工具时，如何让它们稳定共存、自由切换模型后端、并且在长时间任务里不丢失上下文。

我接触这套东西的起因很实际。团队里有人用 Claude Code 写前端，有人用 Codex 处理 Python 脚本，还有人想把本地 LM Studio 的模型接进来省钱。结果就是每个人的终端里塞满了各种环境变量、代理配置、API Key，一旦换机器或者换项目就全乱套。openrig 这类方案的价值就在于把这些零散的配置收敛成一套可复现的骨架。

它适合谁？三类人最需要：一是刚接触 Claude Code 或 Codex、被安装和配置卡住的新手；二是需要在多个模型供应商之间切换的中高级开发者；三是想把本地模型和云端模型混用、控制成本的技术负责人。如果你只是偶尔用一次 AI 写代码，那确实用不上；但只要你的日常工作流里 AI 编程工具占比超过三成，这套编排思路就值得花时间搭起来。

需要提前说明的是，openrig 并不是一个官方发布的单一软件包，它更像是一种工程实践约定——把 Node.js 运行时、tmux 会话管理、模型路由配置、CLI 工具安装这几件事组合成一套稳定的工作环境。下面我会按照实际搭建顺序，把每个环节的原理、参数和踩坑点讲透。

2. 环境底座：Node.js 与 tmux 的选型逻辑

2.1 为什么 Node.js 版本选择是第一道坎

Claude Code 和 Codex 的 CLI 版本绝大多数都是基于 Node.js 生态分发的，这意味着 Node.js 的版本直接决定了你能不能装上、装完能不能跑。热搜里那条error installing 24.21.0: node.js v24.21.0 is not yet released就是典型的版本号写错导致的报错——很多人看到教程里写了个大版本号就照抄，结果那个版本根本还没正式发布。

我的建议很明确：永远优先选 LTS 版本。截至我写这篇内容时，Node.js 的 LTS 主线在 20.x 和 22.x 之间，这两个版本对 Claude Code 和 Codex 的兼容性最稳。奇数版本（如 21.x、23.x）属于过渡版本，生命周期短，某些原生模块编译时容易出问题。

安装方式上，我不推荐直接用系统包管理器装。原因很简单：Ubuntu 自带的 apt 源里 Node.js 版本往往滞后一到两年，而 Claude Code 这类工具更新频繁，版本太旧会直接报不支持。我实测下来最省心的方案是用 nvm（Node Version Manager）来管理多版本：

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并切换到 LTS 版本 nvm install --lts nvm use --lts nvm alias default lts/* # 验证 node -v npm -v

用 nvm 的好处是，当某个工具要求特定 Node 版本时，你可以随时nvm install 20 && nvm use 20切换，不会污染系统环境。Windows 用户可以用 nvm-windows，逻辑一样，只是安装包换成 exe。

注意：如果你在 Windows 上遇到node.js v24.21.0 is not yet released这类报错，先执行nvm list available看看实际可安装的版本列表，不要凭记忆写版本号。

2.2 tmux：被低估的会话保命工具

tmux 在 openrig 这套方案里的角色，是保证长时间 AI 任务不中断。你想想这个场景：让 Claude Code 跑一个重构任务，可能要十几分钟甚至更久，期间你要去看日志、切窗口、甚至 SSH 断线重连。如果没有 tmux，终端一关，任务就没了。

tmux 的核心概念只有三个：会话（session）、窗口（window）、面板（pane）。我通常这样组织：

# 创建一个名为 ai-work 的会话 tmux new -s ai-work # 在会话内按 Ctrl+b 然后按 % 垂直分屏 # 按 Ctrl+b 然后按 " 水平分屏 # 按 Ctrl+b 然后按方向键切换面板 # 脱离会话（任务继续在后台跑） # 按 Ctrl+b 然后按 d # 重新连接会话 tmux attach -t ai-work # 查看所有会话 tmux ls

实际使用中，我会把一个面板留给 Claude Code，一个面板留给 Codex，第三个面板用来看日志或者跑测试。这样三个工具的输出互不干扰，切换成本几乎为零。Ubuntu 上安装 tmux 就是一行sudo apt install tmux，macOS 用brew install tmux。

提示：tmux 默认的前缀键是 Ctrl+b，如果你觉得别扭，可以在~/.tmux.conf里改成 Ctrl+a，跟 screen 保持一致，肌肉记忆更容易迁移。

3. Claude Code 与 Codex 的安装配置实战

3.1 Claude Code 安装：从 npm 到首次运行

Claude Code 的安装本身不复杂，复杂的是网络环境和账号权限。先说过安装：

# 全局安装 npm install -g @anthropic-ai/claude-code # 验证安装 claude --version

装完之后第一次运行claude，它会引导你完成认证。这里有几个高频问题需要提前知道。

第一个是your organization has disabled claude subscription access for claude code这个报错。它的含义是你的账号所属组织关闭了 Claude Code 的访问权限。这种情况通常出现在企业账号上，解决办法是换个人账号，或者让管理员在组织设置里开启对应权限。这不是技术问题，是权限配置问题，折腾命令行没用。

第二个是note: claude code might not be available in your country。这个提示说明当前网络环境不在服务覆盖范围内。我的处理方式是检查自己的网络配置是否符合工具的使用要求，确保在合规前提下使用。

第三个是 VS Code 集成。如果你用 VS Code，可以装 Claude Code 的官方扩展，然后在设置里配置 CLI 路径。实测下来，VS Code 里的体验和终端里基本一致，但终端里用 tmux 管理多会话更灵活。我的习惯是：日常小任务用 VS Code 扩展，大任务丢到 tmux 里跑。

3.2 Codex 安装：Windows 与 Ubuntu 的差异处理

Codex 的安装路径和 Claude Code 类似，也是 npm 全局包为主。但 Windows 用户会遇到更多坑，我单独说一下。

Windows 上推荐用 PowerShell 而不是 CMD，因为 CMD 对某些 npm 脚本的兼容性不好。安装命令：

npm install -g @openai/codex codex --version

如果遇到codex is ignoring 1 unrecognized configuration setting这个警告，说明你的配置文件里有一个键名拼错了。Codex 的配置文件通常在~/.codex/config.json或项目根目录的.codex文件里。我的排查方法是：先把配置文件备份，然后逐段注释掉，看警告什么时候消失，就能定位到具体哪一行有问题。

Ubuntu 上的安装基本一致，但要注意权限问题。如果你用sudo npm install -g，装出来的包属主是 root，普通用户运行时可能读不到配置。正确做法是配置 npm 的全局目录到用户目录下：

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

这样装出来的包都在你的用户目录下，不需要 sudo，也不会污染系统。

3.3 模型后端切换：本地与云端的混合策略

openrig 这套方案最有价值的部分，就是模型后端的灵活切换。热搜里提到的cc switch local proxy failed while handling codex endpoint /responses和使用 cc switch 接入 deepseek v4, qwen, glm等模型，说的都是同一件事：通过一个中间层，把 Claude Code 或 Codex 的请求转发到不同的模型供应商。

这个中间层的原理不复杂。Claude Code 和 Codex 都支持自定义 API 端点（base URL），你只要把端点指向本地的一个转发服务，转发服务再根据配置把请求路由到 DeepSeek、Qwen、GLM 或者 LM Studio 的本地模型即可。

我实测下来，配置的关键在于三点：一是端点路径要匹配，Codex 用的是/responses，Claude Code 用的是/v1/messages，路径写错就会报local proxy failed；二是 API Key 的传递方式要一致，有的供应商用 Bearer Token，有的用自定义 header；三是超时设置要放宽，本地模型首次加载可能要好几十秒。

如果你要把 Claude Code 接到 LM Studio 的本地模型上，大致流程是：在 LM Studio 里启动本地服务，记下端口（默认 1234），然后在 Claude Code 的配置里把 base URL 指向http://localhost:1234/v1，模型名填 LM Studio 里加载的模型标识。这样请求就不会出本机，速度和隐私都有保障。

注意：本地模型的能力和云端模型差距明显，适合做代码补全、格式转换这类轻任务，复杂的架构设计还是建议用云端模型。

4. 多工具协同的工作流设计

4.1 用 tmux 编排 Claude Code 与 Codex 的分工

工具装好了，接下来是怎么让它们协同。我的做法是按任务类型分工：Claude Code 擅长理解大段上下文和做重构，Codex 在生成独立函数和脚本上响应更快。所以我会在 tmux 里开三个面板：

• 面板一：Claude Code，负责读整个项目、做跨文件修改
• 面板二：Codex，负责写独立工具函数、生成测试用例
• 面板三：普通 shell，跑 git 命令、看测试输出

这种分工的好处是，两个 AI 工具的上下文互不污染。你让 Claude Code 读了一堆文件之后，它的上下文窗口占用很高，这时候再让它做别的事效率会下降。分开之后，每个工具都在自己最擅长的场景里工作。

实际操作中，我会用 tmux 的send-keys命令做半自动化。比如把一段需求同时发给两个工具，对比它们的输出：

# 向指定面板发送命令 tmux send-keys -t ai-work:0.0 'claude "重构这个函数"' Enter tmux send-keys -t ai-work:0.1 'codex "重构这个函数"' Enter

这样你可以直观看到两个模型对同一个问题的不同解法，取长补短。

4.2 配置文件的分层管理

多工具协同最大的隐患是配置冲突。Claude Code、Codex、npm、nvm 各自都有一堆配置文件，散落在 home 目录的各个角落。我的做法是建一个~/ai-rig目录，把所有配置集中管理，然后用软链接指回原位。

目录结构大概是这样：

~/ai-rig/ ├── claude/ │ └── settings.json ├── codex/ │ └── config.json ├── tmux/ │ └── tmux.conf └── scripts/ ├── switch-model.sh └── start-session.sh

然后用软链接：

ln -sf ~/ai-rig/claude/settings.json ~/.claude/settings.json ln -sf ~/ai-rig/codex/config.json ~/.codex/config.json ln -sf ~/ai-rig/tmux/tmux.conf ~/.tmux.conf

这样做的好处是，换机器的时候只要把ai-rig目录拷过去，重新建软链接，整个环境就恢复了。比逐个工具重新配置快得多，也不容易漏掉某个隐藏文件。

4.3 会话恢复与任务续跑

AI 编程任务经常是跨天的。今天让 Claude Code 改了一半，明天接着改，怎么保证上下文不丢？我的经验是两条腿走路：一是 tmux 会话不关，机器不重启就能一直 attach 回去；二是重要任务的中间结论手动落到文件里，比如让 AI 把当前进度写成PROGRESS.md，下次直接让它读这个文件。

tmux 会话在机器重启后会丢失，这是它的局限。如果你需要跨重启恢复，可以用 tmux-resurrect 这个插件，它能保存和恢复会话布局。安装方式是在~/.tmux.conf里加一行插件声明，然后用 tpm（tmux plugin manager）管理。不过我的建议是别过度依赖插件，关键任务的进度落盘才是王道。

5. 常见报错与排查速查

5.1 安装类报错

5.2 运行类报错

cc switch local proxy failed while handling codex endpoint /responses这个报错我遇到过好几次，排查下来无非三种原因：转发服务的端点路径没配对，Codex 请求的是/responses但你配的是/v1/responses；转发服务的进程没起来，端口没人监听；API Key 没传对，供应商直接拒绝了请求。排查顺序就是先curl一下转发服务的健康检查端点，确认进程活着，再看日志里的请求路径和实际配置是否一致。

codex is ignoring 1 unrecognized configuration setting是配置键名拼写错误。Codex 的配置校验比较严格，多一个下划线或者大小写不对都会报。我的做法是把配置文件里的键名跟官方文档逐个对照，或者干脆删掉可疑的那一行，看警告是否消失。

your organization has disabled claude subscription access是账号权限问题，前面说过了，换账号或者找管理员开权限，命令行层面无解。

5.3 模型接入类问题

接入 DeepSeek、Qwen、GLM 这类第三方模型时，最常见的坑是模型名写错。每个供应商的模型标识都不一样，比如 DeepSeek 可能是deepseek-chat，Qwen 可能是qwen-max，写错了就会返回 404 或者模型不存在。我的习惯是先用curl直接调供应商的 API 确认模型名可用，再填到配置文件里。

另一个坑是上下文长度。Claude Code 默认假设后端支持很长的上下文，但有些第三方模型或者本地模型的上下文窗口小得多，请求一长就报错。解决办法是在配置里限制单次请求的 token 数，或者把大任务拆成小任务分批处理。

提示：接入任何第三方模型之前，先用一个最简单的请求验证连通性，别一上来就跑复杂任务，否则报错了你分不清是配置问题还是模型能力问题。

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

搭这套环境的过程中，有几个教训是文档里不会写的，我单独拎出来说。

第一个是关于 Node.js 版本切换的。我曾经在一个项目里同时需要 Node 18 和 Node 20，因为两个 AI 工具的依赖树不一样。当时图省事直接改了系统 Node，结果另一个工具崩了。后来老老实实用 nvm，在 tmux 的不同面板里用不同 Node 版本，问题就解决了。nvm 的nvm use是 per-shell 生效的，这正好跟 tmux 的面板隔离特性契合。

第二个是关于 tmux 会话命名的。我一开始随便起名字，时间长了tmux ls出来一堆0、1、2，根本分不清哪个是哪个。后来改成按项目命名，比如proj-web、proj-api，一眼就能找到。这个习惯看似小事，但每天省下的切换时间累积起来很可观。

第三个是关于配置备份的。我有一次重装系统，忘了备份~/.claude目录，结果所有自定义配置全丢了，重新配花了两个小时。从那以后我就把ai-rig目录放进了私有 git 仓库，每次改配置就 commit 一次。配置文件版本化之后，不仅能恢复，还能看到自己什么时候改了什么，排查问题时特别有用。

第四个是关于本地模型的预期的。我一开始想着用 LM Studio 的本地模型完全替代云端，省钱又隐私。实测下来，本地模型在代码补全这种短任务上还行，但一旦涉及跨文件理解、复杂重构，质量差距就出来了。现在的策略是本地模型做初筛和格式化，复杂任务还是交给云端。这个分工不是技术限制，是能力边界的现实。

最后分享一个 tmux 的小技巧：如果你经常需要同时看多个 AI 工具的输出，可以用tmux synchronize-panes把多个面板的输入同步，这样你敲一次命令，所有面板同时执行。适合做对比测试，但平时记得关掉，不然会误操作。

这套 openrig 的搭建思路，核心不是某个具体工具，而是把环境、会话、模型路由这三层解耦。环境层用 nvm 管版本，会话层用 tmux 管生命周期，模型层用转发服务管路由。三层各司其职，任何一层出问题都不会牵连其他层。这个结构搭好之后，你换工具、换模型、换机器，成本都很低。