企业官网建设流程全解析

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

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟“rig”在英文里常指设备支架或矿机机架。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编程助手，大概率已经在某个 issue 或讨论帖里见过它。openrig 本质上是一个面向 AI 编程 CLI 工具的本地运行编排层，它把 Node.js 运行时、tmux 会话管理、模型接入配置、代理转发这几件事打包成一套可复用的脚手架，让你不用每次换机器都从头配一遍环境。

我最初接触它是因为一个很具体的痛点：我在三台机器上分别用 Claude Code 和 Codex，每台机器的 Node 版本不一样，tmux 配置不一样，模型端点也不一样。每次换机器都要重新查一遍“claude code 安装”“codex 安装教程”“node.js 安装”这些关键词，然后重复踩一遍坑。openrig 的出现让我可以把这些配置收敛到一个仓库里，换机器时只需要拉下来跑一个初始化脚本。

它适合什么人？如果你是那种会在 VS Code 里同时开 Claude Code 和 Codex、偶尔还要切到本地 LM Studio 模型、并且希望这些会话在 tmux 里持久化不中断的人，openrig 就是为你准备的。如果你只是偶尔用一下网页版对话，那它可能有点重。但只要你开始把 AI 编程助手当成日常工具，环境管理这件事迟早会变成刚需。

提示：openrig 不是一个模型，也不是一个 API 代理服务，它更像是一个“环境编排约定”。理解这一点很关键，否则你会一直在找它的二进制文件。

2. 核心设计思路拆解：为什么是 Node.js + tmux + 配置层

2.1 为什么运行时选 Node.js 而不是别的

Claude Code 和 Codex 的 CLI 版本目前主流分发方式都是 npm 包，这意味着 Node.js 是硬依赖。你在搜索“node.js是干什么的”或者“node.js下载”的时候，其实就是在解决这个前置条件。openrig 把 Node.js 版本管理纳入自己的职责范围，通常通过.nvmrc或.node-version文件锁定版本，避免出现 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这类问题。

我实测下来，Node.js 的 LTS 版本是最稳的选择。当前 LTS 线在 20.x 和 22.x 之间，24.x 虽然新但生态跟进不完全，某些 npm 包在 24.x 上会出现原生模块编译失败。openrig 的默认策略是锁定 LTS，这个决策背后是有道理的：AI 编程工具的依赖树通常比较深，用 LTS 能减少 80% 以上的兼容性问题。

2.2 tmux 在这里扮演什么角色

很多人第一次看到 openrig 依赖 tmux 会疑惑：我只是跑个 CLI 工具，为什么要用终端复用器？原因在于 Claude Code 和 Codex 都是长会话型工具。你发起一个任务后，它可能跑几分钟甚至十几分钟，期间你需要看日志、中途干预、或者切出去干别的事。如果没有 tmux，SSH 一断会话就没了，任务白跑。

tmux 让这些会话变成“可附着、可分离”的。你可以早上发起一个 Codex 任务，detach 之后去开会，回来再 attach 看结果。openrig 把 tmux 的 session 命名、窗口布局、日志落盘都做了约定，比如每个项目一个 session，每个 session 里固定几个 window 分别跑 Claude Code、Codex 和 shell。这种约定看起来简单，但省去了每次手动tmux new -s再Ctrl+b c的重复劳动。

2.3 配置层为什么要单独抽出来

Claude Code 和 Codex 的配置格式不一样，Claude Code 走的是自己的 settings 文件加环境变量，Codex 走的是 TOML 配置加组织设置。你在搜索“codex无法加载组织设置”“codex is ignoring 1 unrecognized configuration setting”的时候，遇到的就是配置层的问题。openrig 的做法是把这些配置模板化，用变量替换的方式生成最终配置文件。

这样做的好处是，当你需要从官方端点切到第三方 API 或者本地 LM Studio 时，只需要改一个变量，而不是去翻三个不同的配置文件。我见过太多人因为改错一个字段导致 “cc switch local proxy failed while handling codex endpoint /responses” 这种报错，然后花半天排查。配置集中管理能直接消灭这类问题。

3. 环境准备与安装实操：从裸机到可运行

3.1 Node.js 安装的版本选择与验证

不管你用 Ubuntu、macOS 还是 Windows，第一步都是把 Node.js 装对。我的建议是不要用系统包管理器自带的 Node，版本往往太旧。用 nvm 或者 fnm 这类版本管理器，能让你在不同项目间切换 Node 版本。

# 以 nvm 为例，安装 LTS nvm install --lts nvm use --lts node -v npm -v

验证的时候注意看node -v输出的版本号。如果输出的是v24.x而你并没有主动装 24，说明系统里有个更高优先级的 Node 在 PATH 前面。这时候用which node查一下路径，大概率是某个全局安装覆盖了 nvm 的 shim。

注意：Windows 用户如果遇到 “node.js v24.21.0 is not yet released or is not available” 这类报错，通常是因为 nvm-windows 的版本列表没更新。先nvm list available看实际可用版本，再装。

3.2 tmux 安装与基础配置

Linux 和 macOS 上 tmux 基本一条命令搞定：

# Ubuntu/Debian sudo apt install tmux # macOS brew install tmux

Windows 原生没有 tmux，但如果你在 WSL2 里跑 openrig，tmux 就能正常工作。这也是我推荐 Windows 用户走 WSL2 路线的原因，Claude Code 和 Codex 在 WSL2 里的表现比原生 Windows 稳定得多。

tmux 装完后建议改一下默认前缀键，Ctrl+b和很多编辑器的快捷键冲突。我在~/.tmux.conf里改成Ctrl+a，并且开启鼠标支持：

set -g prefix C-a bind C-a send-prefix set -g mouse on set -g history-limit 50000

history-limit调大很重要，AI 编程工具的输出经常很长，默认 2000 行不够翻。

3.3 openrig 本身的获取与初始化

openrig 通常以仓库形式分发，clone 下来后跑初始化脚本：

git clone <openrig-repo> cd openrig ./init.sh

初始化脚本一般会做几件事：检查 Node 版本、检查 tmux 是否存在、生成配置文件模板、创建默认 tmux session。如果脚本报错，先看它检查的是哪个依赖，八成是 Node 版本不对或者 tmux 没装。

我踩过的一个坑是：初始化脚本在 macOS 上默认用greadlink，但系统里只有readlink。解决办法是brew install coreutils，或者手动改脚本里的命令。这类小问题在跨平台项目里很常见，遇到不要慌，看报错行改就行。

4. Claude Code 与 Codex 的接入配置细节

4.1 Claude Code 的安装与端点配置

Claude Code 的安装本身不复杂，npm 全局装即可：

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

装完后第一次运行会引导你登录。如果你遇到 “your organization has disabled claude subscription access for claude code” 或者 “claude code might not be available in your country”，那是账号层面的限制，不是安装问题。这种情况下你需要走第三方 API 或者本地模型路线。

openrig 在这里的价值是帮你管理多套端点配置。比如你白天用官方端点，晚上切到本地 LM Studio，只需要在 openrig 的配置里改一个 profile 名。Claude Code 支持通过环境变量指定 base URL 和 API key，openrig 会把这些环境变量在 tmux session 启动时注入。

# 示例：指向本地 LM Studio export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="lm-studio"

提示：本地 LM Studio 的端点路径要和 Claude Code 期望的格式对齐，否则会出现 404。LM Studio 默认的 OpenAI 兼容端点是/v1，但 Claude Code 可能期望/v1/messages，这个要在 LM Studio 的 server 配置里确认。

4.2 Codex 的安装与常见配置错误

Codex 的安装同样走 npm，但它的配置格式是 TOML，容易写错。常见的报错 “codex is ignoring 1 unrecognized configuration setting. check for typos” 基本都是字段名拼错或者缩进不对。

# ~/.codex/config.toml 示例 model = "gpt-5" provider = "openai" [providers.openai] base_url = "https://api.openai.com/v1" api_key_env = "OPENAI_API_KEY"

注意api_key_env这个字段，它指的是“从哪个环境变量读 key”，而不是直接写 key。很多人在这里直接写 key 字符串，结果 Codex 读不到。openrig 的模板里会把这个字段标红注释，减少这类错误。

Codex 接入 DeepSeek 或者其他第三方模型时，关键是base_url要指向兼容 OpenAI 格式的端点。DeepSeek 的端点格式和 OpenAI 基本一致，改base_url和model两个字段就能跑。

4.3 在 VS Code 里同时用两个工具

VS Code 配置 Claude Code 和 Codex 的核心是终端集成。你可以在 VS Code 的settings.json里配置默认终端为 tmux，这样每次打开终端就自动进入 openrig 管理的 session。

{ "terminal.integrated.defaultProfile.linux": "tmux", "terminal.integrated.profiles.linux": { "tmux": { "path": "tmux", "args": ["attach", "-t", "openrig"] } } }

这样你在 VS Code 里开终端，直接就在 openrig 的 session 里，Claude Code 和 Codex 的窗口都在，切换用Ctrl+a加数字就行。实测这个配置能省掉大量“打开终端→cd 到项目→启动工具”的重复操作。

5. 多模型切换与本地模型接入实战

5.1 用 cc switch 思路管理多端点

社区里有个叫 cc switch 的做法，核心思路是用一个切换脚本在不同 API 端点之间跳。openrig 把这个思路固化下来，提供rig switch <profile>命令。profile 定义在 YAML 里：

profiles: official: base_url: "https://api.anthropic.com" api_key_env: "ANTHROPIC_API_KEY" deepseek: base_url: "https://api.deepseek.com/v1" api_key_env: "DEEPSEEK_API_KEY" local: base_url: "http://localhost:1234/v1" api_key_env: "LM_STUDIO_KEY"

切换的时候，openrig 会重写 Claude Code 和 Codex 的配置文件，然后重启 tmux session 里的对应窗口。这个过程看起来暴力，但比手动改配置可靠得多，因为手动改总会漏掉某个字段。

5.2 本地 LM Studio 模型的接入要点

本地模型接入最大的坑是上下文长度和并发数。LM Studio 默认的上下文可能只有 4096，而 Claude Code 的系统提示词本身就超过这个数，结果就是模型一直截断，表现得很“笨”。你需要在 LM Studio 的 server 设置里把 context length 调到 32768 以上，具体看你的显存。

另一个坑是模型名称。Claude Code 会发送特定的 model 字段，如果 LM Studio 里加载的模型名不匹配，就会报 model not found。解决办法是在 LM Studio 里把模型名改成 Claude Code 期望的名字，或者在 openrig 配置里做名称映射。

我实测下来，7B 到 14B 的模型跑 Claude Code 的体验只能算“能用”，复杂任务还是得靠云端大模型。本地模型更适合做代码补全、简单重构这类轻量任务。

5.3 端点切换后的验证清单

每次切换端点后，不要直接开始干活，先跑一个最小验证：

1. 在 tmux 里 attach 到对应窗口
2. 输入一个简单 prompt，比如“列出当前目录文件”
3. 观察是否有报错，特别是 401、404、timeout
4. 检查日志文件里是否有 “local proxy failed” 之类的字样

这个清单看起来啰嗦，但能帮你在一分钟内定位问题，而不是干了半小时才发现端点根本没通。

6. 常见问题排查与避坑经验实录

6.1 安装阶段的典型报错

6.2 运行阶段的会话管理问题

tmux session 丢失是最常见的问题。原因通常是机器重启或者 tmux server 被杀。openrig 的做法是提供一个rig restore命令，根据配置文件重建 session。但如果你没保存配置，就只能手动重建。

我的经验是，把 openrig 的配置目录纳入 git 管理，每次改完配置就 commit。这样换机器或者重装系统后，clone 下来就能恢复。配置文件里不要写明文 API key，用环境变量引用，key 单独存在一个不纳入 git 的文件里。

另一个问题是 tmux 窗口里的进程僵死。Claude Code 或 Codex 偶尔会卡住不输出，这时候Ctrl+c不一定能杀掉。我的做法是在 tmux 里开一个专门的“管理窗口”，用htop或者ps aux | grep找到僵死进程，手动 kill。openrig 可以配置一个快捷键来快速执行这个操作。

6.3 模型接入的隐蔽坑

“codex破甲”这个搜索词背后其实是一个常见需求：让 Codex 突破默认的安全限制或者上下文限制。我不建议走这条路，因为绕过限制往往会导致输出质量下降甚至产生有害内容。更合理的做法是换一个限制更宽松的模型，或者把任务拆小。

另一个隐蔽坑是时区。Claude Code 和 Codex 的日志时间戳默认用 UTC，如果你用本地时间去看日志，会以为任务跑了很久其实只跑了几分钟。在 openrig 的配置里把TZ环境变量设成你本地时区，日志可读性会好很多。

7. 日常使用中的效率技巧

7.1 tmux 窗口布局的固定套路

我习惯每个项目一个 session，里面固定四个窗口：

• 窗口 0：Claude Code
• 窗口 1：Codex
• 窗口 2：shell（用于 git 操作、跑测试）
• 窗口 3：日志 tail（tail -f看两个工具的日志）

openrig 的默认布局和这个略有不同，但你可以改配置。固定布局的好处是肌肉记忆，Ctrl+a 0就是 Claude，Ctrl+a 1就是 Codex，不用想。

7.2 日志落盘与回溯

Claude Code 和 Codex 的输出默认只在终端里，session 一关就没了。openrig 会把输出同时写到~/.openrig/logs/下，按日期和工具名分文件。这样你可以在事后回溯某个任务到底发生了什么。

日志文件会越来越大，建议加一个 logrotate 规则，或者用 openrig 自带的清理命令定期删旧日志。我一般保留最近 7 天，再久的就压缩归档。

7.3 多机器同步配置

如果你和我一样在多台机器上用 openrig，配置同步是个问题。我的做法是把 openrig 的配置目录做成一个 git 仓库，每台机器 clone 同一份，然后用一个sync.sh脚本拉取更新并重启 session。注意 API key 不要进 git，用.gitignore排除掉。

跨平台同步时注意路径分隔符和换行符。Windows 的 CRLF 会让 shell 脚本报奇怪的错，在 git 里配core.autocrlf=input能避免大部分问题。

8. 我对 openrig 这类工具的实际体会

用了几个月下来，openrig 最大的价值不是它提供了什么新功能，而是它把一堆琐碎的环境问题收敛了。以前我每换一台机器，光配 Claude Code 和 Codex 的环境就要花一两个小时，现在十分钟搞定。这个时间节省在长期来看很可观。

它也不是没有缺点。配置模板有时候更新不及时，新版本的 Claude Code 加了新字段，openrig 的模板里没有，你得手动补。另外它对 Windows 原生支持一般，WSL2 是必须的。如果你不用 tmux，那 openrig 的一半价值就没了。

最后分享一个小技巧：openrig 的 session 名字默认是openrig，如果你同时跑多个项目，建议改成项目名。在配置里加一行session_name: <project>就行。这样tmux ls的时候一眼就能看出哪个 session 对应哪个项目，不用猜。