企业官网建设流程全解析

1. 从"openrig"这个名字说起：它到底想解决什么问题

第一次看到openrig这个词，我脑子里蹦出来的画面是矿场里的钻井平台——rig 在英文里本来就有"钻井架、装备架"的意思。放到 AI 编程工具的语境里，这个命名其实挺传神：它想做的，就是给 Claude Code、Codex 这类命令行 AI 编程助手搭一个统一的"装备架"，让你不用在多个工具、多个模型、多个终端会话之间来回折腾。

先把结论摆在前面：openrig不是一个模型，也不是一个 IDE 插件，它更像是一层编排与桥接层。从它关联的热词就能看出端倪——Claude Code、Codex、Node.js、tmux，这四个词几乎勾勒出了它的全部技术底座。Claude Code 和 Codex 是当前最主流的两类终端 AI 编程代理（agent），Node.js 是它们的运行时依赖，tmux 则是让这些长驻进程在后台稳定存活、随时可切换的会话管理工具。openrig要做的，就是把这几样东西拧成一股绳。

为什么这件事值得单独做一个项目？因为实际用过 Claude Code 或 Codex 的人都知道，痛点非常具体。你装完 Claude Code，发现它默认走官方订阅，想接本地模型（比如 LM Studio 起的本地推理服务）或者第三方 API，就得改环境变量、改配置文件，稍不留神就报cc switch local proxy failed while handling codex endpoint /responses这种让人一头雾水的错。你装完 Codex，又发现它和 Claude Code 的配置格式、认证方式、模型命名规则完全不一样，{"detail":"the 'gpt-5.6-sol' model is not supported when using codex with a..."}这类报错能让你排查半天。更别提还有codex is ignoring 1 unrecognized configuration setting这种"配置写了但没生效"的隐性坑。

openrig的价值就在于：它试图把这些碎片化的配置、认证、模型路由、会话管理统一到一个"架子"上。你不再需要为每个工具单独记一套配置语法，也不用担心切换模型时把环境搞乱。对于同时用 Claude Code 和 Codex、又想在本地模型和云端模型之间灵活切换的开发者来说，这就是刚需。

这篇文章适合谁看？三类人：第一类是完全没接触过 Claude Code / Codex，想从零搭一套能跑起来的环境的新手；第二类是已经装了但被各种报错和配置冲突折磨过的中级用户；第三类是想把 AI 编程代理集成进自己工作流、甚至想基于openrig思路做二次开发的老手。我会从环境准备一路讲到多工具协同、模型路由、会话保活，把踩过的坑和验证过的方案都摊开讲。

提示：本文涉及的所有工具均为本地开发辅助工具，配置过程全部在你自己的机器上完成，不涉及任何网络代理相关内容。所有模型接入均指通过官方或本地推理服务提供的标准 API 接口。

2. Node.js 运行时：整个装备架的地基怎么打

2.1 为什么 Claude Code 和 Codex 都绕不开 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 or is not available——这个报错的意思是，你试图安装的 Node.js 版本号根本不存在，或者你的包管理器源里还没有这个版本。

这里有个反直觉的点：不是 Node.js 版本越新越好。Claude Code 和 Codex 对 Node.js 有明确的版本区间要求，通常建议 LTS（长期支持）版本。截至我写这篇内容时，Node.js 20.x 和 22.x 的 LTS 是最稳妥的选择。24.x 虽然新，但很多 AI 工具的依赖链还没完全适配，贸然上最新版容易遇到原生模块编译失败的问题。

在 Ubuntu 上装 Node.js，我不推荐直接用apt install nodejs，因为系统源里的版本往往偏旧。更可靠的做法是用 NodeSource 的源，或者用 nvm（Node Version Manager）做版本管理。nvm 的好处是你可以同时装多个版本，随时切换，这对需要测试不同工具兼容性的人来说非常实用。

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v npm -v

装完之后node -v应该输出v20.x.x。如果你在 Windows 上，建议直接去 Node.js 官网下载 LTS 版本的安装包，安装时勾选"Add to PATH"，省去手动配环境变量的麻烦。Windows 下用 nvm-windows 也可以，但体验不如 Linux/macOS 顺滑，偶尔会遇到权限问题。

2.2 npm 全局目录与权限：一个容易被忽略的坑

Node.js 装好了，接下来装 Claude Code 或 Codex 时，很多人会遇到EACCES权限错误。这是因为 npm 默认的全局安装目录需要 root 权限。有两种解法：一是每次都用sudo npm install -g，但这会带来后续权限混乱；二是把 npm 的全局目录改到用户目录下。

# 创建用户级全局目录 mkdir -p ~/.npm-global # 配置 npm 使用该目录 npm config set prefix '~/.npm-global' # 把该目录加入 PATH（写入 ~/.bashrc 或 ~/.zshrc） export PATH=~/.npm-global/bin:$PATH source ~/.bashrc

这样配完之后，npm install -g就不需要 sudo 了，后续升级工具也不会因为权限问题失败。这个细节看起来小，但它能帮你避开后面一连串莫名其妙的报错。

2.3 验证运行时是否真的就绪

装完 Node.js 和 npm 之后，别急着装 AI 工具，先做一轮基础验证。我习惯跑这几个命令：

node -v # 确认版本 npm -v # 确认 npm 可用 npm config get prefix # 确认全局目录 which node # 确认 node 路径

如果which node指向的是 nvm 管理的路径（比如~/.nvm/versions/node/v20.x.x/bin/node），说明 nvm 生效正常。如果指向/usr/bin/node，那可能是系统自带的旧版本在干扰，需要检查 PATH 顺序。

注意：如果你之前用 apt 装过 nodejs，nvm 和系统版本可能共存，导致node -v和which node结果不一致。这种情况下建议sudo apt remove nodejs清理掉系统版本，避免版本冲突。

3. Claude Code 与 Codex 的安装、认证与首次跑通

3.1 Claude Code 的安装路径与认证方式

Claude Code 通过 npm 全局安装：

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

装完之后在终端输入claude就能启动。首次启动会引导你完成认证。这里有个关键分叉：你是用官方订阅，还是接第三方 API / 本地模型？

如果你用官方订阅，直接按引导登录即可。但如果你看到your organization has disabled claude subscription access for claude code这个报错，说明你的账号所属组织关闭了 Claude Code 的订阅访问权限。这种情况下，你需要走 API Key 的方式，或者联系组织管理员。

接第三方 API 或本地模型时，核心是配置环境变量。Claude Code 支持通过ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY来指定自定义端点。比如你想让它调用 LM Studio 起的本地模型：

export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="lm-studio" claude

LM Studio 默认在 1234 端口提供 OpenAI 兼容的 API。但要注意，Claude Code 期望的是 Anthropic 格式的 API，而 LM Studio 提供的是 OpenAI 格式，两者并不完全兼容。这就是为什么很多人接本地模型时会失败——协议对不上。解决办法是用一个转换层（比如 LiteLLM 之类的代理工具）把 OpenAI 格式转成 Anthropic 格式，或者直接用支持 Anthropic 协议的本地推理服务。

3.2 Codex 的安装与它和 Claude Code 的差异

Codex CLI 的安装方式类似：

npm install -g @openai/codex

但 Codex 的配置体系和 Claude Code 完全不同。Codex 用~/.codex/config.toml或环境变量来配置，认证走 OpenAI 的 API Key 或登录流程。常见的报错codex登录不上通常和网络环境、API Key 有效性、或者组织设置有关。而codex无法加载组织设置则往往是因为你的账号在组织里没有对应的权限配置。

Codex 接第三方模型（比如 DeepSeek）时，需要改config.toml里的model_provider和base_url。这里有个大坑：Codex 对模型名称有白名单校验，你写一个它不认识的模型名，就会报the 'gpt-5.6-sol' model is not supported when using codex with a...。解决办法是查 Codex 官方文档支持的模型列表，或者用它的model_providers自定义配置来绕过校验。

3.3 两个工具的核心差异对照

这张表是我实际用下来总结的，不是官方文档抄的。理解这些差异，你才能在openrig这类编排层里正确地路由请求。

3.4 首次跑通的验证清单

装完两个工具后，别急着上复杂配置，先各自跑一个最小验证：

1. claude --version和codex --version确认安装成功
2. 在空目录下启动claude，问一个简单问题，确认能收到回复
3. 同样启动codex，确认基础对话可用
4. 检查各自的配置文件位置，确认没有语法错误

我踩过的一个坑是：Claude Code 和 Codex 同时装在全局目录下，某些共享依赖版本冲突，导致其中一个启动时报模块找不到。解决办法是给它们分别用独立的 Node.js 版本（nvm 切换），或者确保全局依赖树干净。

4. tmux 会话保活：让 AI 代理在后台稳定干活

4.1 为什么 AI 编程代理需要 tmux

Claude Code 和 Codex 都是长驻进程，一次任务可能跑几分钟甚至更久。如果你直接在 SSH 会话里跑，网络一断，进程就没了，之前的工作全白费。tmux 解决的就是这个问题：它创建一个持久化的终端会话，你断开连接后会话继续存在，重新连上就能恢复。

更重要的是，openrig这类编排工具往往需要同时管理多个 AI 代理会话——一个跑 Claude Code 处理前端代码，一个跑 Codex 处理后端逻辑，还有一个跑测试。用 tmux 可以给每个会话起个名字，随时切换，互不干扰。

# 创建名为 claude-work 的会话 tmux new -s claude-work # 在会话里启动 Claude Code claude # 按 Ctrl+B 然后按 D 脱离会话（进程继续运行） # 重新连接 tmux attach -t claude-work # 列出所有会话 tmux ls

4.2 tmux 配置里值得改的几个默认项

tmux 默认配置有几个反人类的地方，我建议在~/.tmux.conf里改掉：

# 把前缀键从 Ctrl+B 改成 Ctrl+A（更顺手） set -g prefix C-a unbind C-b bind C-a send-prefix # 开启鼠标支持（可以点击切换面板） set -g mouse on # 设置更大的回滚缓冲区（AI 输出很长，默认 2000 行不够） set -g history-limit 50000 # 窗口编号从 1 开始 set -g base-index 1 setw -g pane-base-index 1

history-limit这个特别重要。AI 代理的输出动辄几百行，默认缓冲区很快就被冲掉了，你想往上翻看之前的输出都翻不到。设成 50000 行之后，基本够用。

4.3 用 tmux 编排多代理工作流

假设你要同时跑 Claude Code 和 Codex，可以这样组织：

# 创建主会话 tmux new -s openrig -d # 在会话里创建第一个窗口跑 Claude Code tmux new-window -t openrig -n claude tmux send-keys -t openrig:claude 'claude' C-m # 创建第二个窗口跑 Codex tmux new-window -t openrig -n codex tmux send-keys -t openrig:codex 'codex' C-m # 创建第三个窗口跑日志监控 tmux new-window -t openrig -n logs tmux send-keys -t openrig:logs 'tail -f ~/.openrig/logs/*.log' C-m

这样你一个tmux attach -t openrig就能在三个窗口之间用Ctrl+A加数字切换。这套编排思路就是openrig想标准化的东西——把会话管理、进程启动、日志监控统一起来。

提示：tmux 会话在系统重启后会丢失。如果你需要开机自动恢复，可以配合 systemd 服务或者写一个启动脚本，在登录时自动重建会话。但要注意，AI 代理的认证状态可能不会自动恢复，需要重新登录。

5. 模型路由与配置冲突：那些报错背后的真实原因

5.1cc switch local proxy failed到底在说什么

这个报错cc switch local proxy failed while handling codex endpoint /responses是很多人切换模型时遇到的。拆开看：cc switch是切换配置的动作，local proxy是本地代理层，codex endpoint /responses是 Codex 的响应接口。整句话的意思是：切换配置时，本地代理在处理 Codex 的/responses端点时失败了。

根因通常有三个：第一，代理层没有正确识别 Codex 的 API 格式（OpenAI 格式 vs Anthropic 格式）；第二，切换后的模型端点不可达或返回了非预期格式；第三，配置文件里有残留的旧配置，和新配置冲突。

排查顺序我建议这样：先确认目标模型端点能独立访问（用 curl 直接打），再检查代理层的日志看它把请求转发到了哪里，最后对比新旧配置文件的差异。很多时候问题就出在配置文件里同时存在两套 provider 定义，代理不知道该用哪个。

5.2codex is ignoring 1 unrecognized configuration setting的隐性坑

这个警告看起来无害，但它意味着你写的某个配置项 Codex 根本不认识，直接被忽略了。如果你以为这个配置生效了，实际没有，后面就会遇到"明明配了却不工作"的诡异现象。

常见的 unrecognized setting 包括：拼写错误的键名（比如model_provider写成model_providers）、版本不支持的配置项、放错层级的配置。解决办法是查 Codex 对应版本的配置文档，逐项核对。我习惯把配置项分成"确认支持"和"待验证"两类，待验证的先用最小配置测试，确认生效后再加进去。

5.3 多工具共存时的配置隔离策略

Claude Code 和 Codex 如果都接同一个第三方 API，很容易出现配置互相干扰。我的做法是按工具隔离配置：

• Claude Code 的配置放在独立的 env 文件里，启动时 source
• Codex 的配置放在~/.codex/config.toml，不和其他工具共享
• 本地模型的路由配置单独放一份，用环境变量注入

# ~/.openrig/env/claude.env export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="local-key" # ~/.openrig/env/codex.env export OPENAI_BASE_URL="http://localhost:1234/v1" export OPENAI_API_KEY="local-key"

启动时按需 source 对应的文件，避免全局环境变量污染。这样即使两个工具同时跑，也不会因为环境变量冲突而报错。

5.4 模型名称校验的绕过思路

Codex 对模型名的白名单校验是很多人的拦路虎。当你用一个自定义模型名时，它会直接拒绝。绕过思路有两个：一是用 Codex 支持的模型名做别名映射，在代理层把请求里的模型名替换成真实模型名；二是用model_providers自定义 provider，声明你自己的模型列表。

第一种方案更通用，因为它不依赖 Codex 的配置能力。你可以在本地起一个轻量代理，收到 Codex 的请求后，把model字段替换成实际模型名，再转发给真正的推理服务。这样 Codex 以为自己在调官方模型，实际调的是你的本地模型。

6. 把 openrig 的思路落地成自己的工作流

6.1 目录结构设计

基于openrig的编排理念，我建议这样组织你的工作目录：

~/.openrig/ ├── env/ # 各工具的环境变量文件 │ ├── claude.env │ └── codex.env ├── config/ # 工具配置文件 │ ├── codex-config.toml │ └── proxy-config.yaml ├── logs/ # 运行日志 ├── scripts/ # 启动、切换、监控脚本 │ ├── start-claude.sh │ ├── start-codex.sh │ └── switch-model.sh └── sessions/ # tmux 会话状态记录

这个结构的好处是：配置、日志、脚本分离，出问题时能快速定位。切换模型时只改env/下的文件，不影响其他部分。

6.2 一键启动脚本

#!/bin/bash # ~/.openrig/scripts/start-claude.sh # 加载环境变量 source ~/.openrig/env/claude.env # 检查 tmux 会话是否已存在 if tmux has-session -t claude-work 2>/dev/null; then echo "会话已存在，正在连接..." tmux attach -t claude-work else echo "创建新会话..." tmux new -s claude-work -d tmux send-keys -t claude-work 'claude' C-m tmux attach -t claude-work fi

这个脚本做了两件事：检查会话是否存在，存在就连接，不存在就创建。这样你无论什么时候执行，结果都是"进入一个可用的 Claude Code 会话"。

6.3 模型切换的原子化操作

切换模型最容易出问题的地方是"改了一半"。比如你改了环境变量但没重启进程，或者改了配置文件但代理没重载。原子化操作的意思是：要么全部生效，要么全部不生效。

#!/bin/bash # ~/.openrig/scripts/switch-model.sh MODEL=$1 ENV_FILE=~/.openrig/env/claude.env # 备份当前配置 cp $ENV_FILE ${ENV_FILE}.bak # 写入新配置 sed -i "s|ANTHROPIC_BASE_URL=.*|ANTHROPIC_BASE_URL=\"$MODEL\"|" $ENV_FILE # 验证新端点可达 if ! curl -s --max-time 5 "$MODEL/health" > /dev/null; then echo "新端点不可达，回滚配置" mv ${ENV_FILE}.bak $ENV_FILE exit 1 fi # 重启会话 tmux kill-session -t claude-work 2>/dev/null source $ENV_FILE tmux new -s claude-work -d tmux send-keys -t claude-work 'claude' C-m echo "切换完成，已重启会话"

这个脚本的关键是"先验证再切换"，端点不可达就回滚，避免把环境搞坏。

6.4 日志与可观测性

AI 代理跑起来之后，你需要知道它在干什么。我建议至少记录三类日志：启动日志（记录用了哪个配置、哪个模型）、请求日志（记录每次 API 调用的耗时和状态）、错误日志（记录所有非 200 响应）。

# 在启动脚本里加日志重定向 tmux send-keys -t claude-work 'claude 2>&1 | tee -a ~/.openrig/logs/claude-$(date +%Y%m%d).log' C-m

这样每个会话的输出都会同时显示在终端和写入日志文件。出问题时翻日志，比凭记忆排查快得多。

7. 我踩过的几个真实坑和对应的解法

7.1 版本不匹配导致的"装上了但跑不起来"

有一次我帮朋友配环境，Node.js 装的是 24.x，Claude Code 装上了，但一启动就报原生模块加载失败。折腾了半天才发现是 Node.js 版本太新，某个依赖还没适配。降到 20 LTS 之后立刻正常。这个教训是：AI 工具链对 Node.js 版本敏感，别盲目追新，LTS 才是稳妥选择。

7.2 环境变量污染导致的"配置不生效"

我习惯在~/.bashrc里 export 一堆环境变量，结果 Claude Code 和 Codex 同时读到了对方的配置，行为变得诡异。后来改成按需 source 独立 env 文件，问题消失。如果你也遇到"明明配了却不生效"，先检查env | grep -i api看看有没有多余的环境变量在干扰。

7.3 tmux 会话里的认证状态丢失

tmux 会话保活很好用，但有个坑：如果你在会话里完成了 Claude Code 的登录，然后系统重启，tmux 会话没了，重新创建会话后需要重新登录。认证 token 通常存在~/.claude/或类似目录下，只要这个目录没被清理，重新登录时可能自动恢复。但如果 token 过期了，还是得手动重新认证。我的做法是把认证相关的目录加入备份，避免重装系统后重新配置。

7.4 本地模型接入时的协议不兼容

前面提过，Claude Code 要 Anthropic 格式，LM Studio 给的是 OpenAI 格式。我试过直接用，报了一堆格式错误。后来用一个轻量转换层把 OpenAI 格式转成 Anthropic 格式，才跑通。如果你不想自己写转换层，可以找现成的开源代理工具，配置好映射规则即可。核心是要理解：协议转换的关键是请求体和响应体的字段映射，尤其是messages、model、max_tokens这几个字段。

8. 关于 openrig 这类编排思路的延伸想法

openrig目前还是个相对早期的概念，但它的方向很明确：随着 AI 编程代理越来越多（Claude Code、Codex，未来还会有更多），开发者需要一个统一的编排层来管理它们。这个编排层要解决的核心问题包括：配置统一、模型路由、会话保活、日志聚合、成本追踪。

我自己在实际使用中的体会是，与其等一个完美的工具出现，不如先用手头的 tmux + 脚本 + 环境变量隔离把工作流搭起来。这套土办法虽然不优雅，但足够可靠，而且你完全掌控每个环节。等openrig这类工具成熟了，再迁移过去也不迟。

最后分享一个小技巧：给每个 AI 代理会话起一个有意义的名字，比如claude-frontend、codex-backend、test-runner，而不是默认的0、1、2。这样tmux ls的时候一眼就能看出哪个会话在干什么，切换的时候也不用猜。这个习惯帮我省了不少时间，尤其是在同时跑四五个会话的时候。