企业官网建设流程全解析

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，我下意识以为是某个硬件外设的开源项目，毕竟 rig 这个词在英文里常指“装备、装置”。但翻了一圈社区讨论和仓库结构之后才反应过来，它其实是围绕 AI 编程助手生态做的一套配置编排方案，核心解决的是 Claude Code、Codex 这类命令行智能体在本地环境里“装得上、连得通、切得快”的问题。说白了，openrig 不是某个单一工具，而是一层把 Node.js 运行时、YAML 配置、模型端点、代理转发串起来的胶水层。

为什么会有这么个东西存在？因为现在用 AI 编程助手的人越来越多，但真正卡住大家的往往不是模型能力，而是环境。你装 Claude Code 要 Node.js，装 Codex 也要 Node.js，两个工具对 Node 版本的要求还不一定一致；你想让它们调用本地模型或者第三方端点，就得改配置；配置格式又是 YAML，缩进错一个空格就报错。openrig 想做的就是把这些零碎环节收敛成一套可复用的编排逻辑，让你换模型、换工具、换机器的时候不用从头再来。

它适合谁？我觉得三类人最需要：一是刚接触 Claude Code 或 Codex、被安装步骤劝退的新手；二是同时用多个 AI 编程工具、需要频繁切换模型端点的进阶用户；三是在团队里负责统一开发环境、想让同事开箱即用的工程负责人。如果你只是偶尔用网页版聊天，那 openrig 对你意义不大；但只要你打算把 AI 助手真正嵌进日常编码流程，这套东西迟早会碰到。

我自己的判断是，openrig 的价值不在于它发明了什么新技术，而在于它把一堆散落的实践固化成了结构。Node.js 是底座，YAML 是描述语言，Claude Code 和 Codex 是上层应用，openrig 是中间那层“让它们别打架”的调度层。理解这个定位，后面所有配置和排查都会顺很多。

2. 核心思路拆解：为什么是 Node.js + YAML 这套组合

2.1 Node.js 作为运行时底座的原因

Claude Code 和 Codex 的 CLI 版本基本都是 Node.js 生态的产物，这不是偶然。Node.js 的包管理机制让工具分发变得极其简单，一条 npm 命令就能把整个 CLI 装到全局，跨平台一致性也比较好。你在 Windows、macOS、Ubuntu 上装 Node.js 之后，后续的 Claude Code 安装、Codex 安装流程几乎一模一样，这对社区教程的传播非常友好。

但 Node.js 也带来一个经典痛点：版本碎片化。我见过太多人卡在error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这种报错上，本质是版本号写错了或者源里还没有这个版本。还有人装了 Node.js 之后 Claude Code 能跑、Codex 报错，或者反过来，原因往往是某个工具依赖的 Node 版本区间不同。openrig 的思路是用 YAML 把 Node 版本要求显式声明出来，而不是靠口头约定“你装个 LTS 就行”。

提示：Node.js 官网下载页面有 LTS 和 Current 两个通道，生产环境优先选 LTS，Current 版本虽然新但生态兼容性偶尔会出问题。

2.2 YAML 承担配置描述角色的逻辑

为什么不用 JSON 或者 TOML？JSON 写起来太啰嗦，不能写注释，配置一长就没法维护；TOML 虽然友好但嵌套表达能力弱一些。YAML 的优势在于层级清晰、支持注释、适合描述“环境-工具-模型”这种多层结构。openrig 用 YAML 来定义每个 rig 的组成，比如用哪个 Node 版本、装哪些 CLI、每个 CLI 指向哪个模型端点、走不走本地代理。

YAML 的坑也很集中：缩进必须用空格不能用 Tab，冒号后面要留空格，字符串里的特殊字符要引号包裹。我踩过最典型的一次是cc switch local proxy failed while handling codex endpoint /responses这个报错，排查半天发现是 YAML 里 endpoint 的 URL 少写了一个斜杠，导致代理转发时路径拼接错误。这种问题不看配置根本想不到。

2.3 把 Claude Code 和 Codex 放在同一套编排里的考量

单独用 Claude Code 或者单独用 Codex，其实不需要 openrig 这么一层。真正需要编排的场景是：你白天用 Claude Code 写业务代码，晚上用 Codex 跑一些批量重构，两个工具想共用同一套模型端点配置，或者你想在两者之间快速切换本地模型和云端模型。openrig 把这种切换抽象成 YAML 里的一个字段，改一行配置就能换端点，不用去翻每个工具各自的配置文件。

这里有个设计取舍值得说：openrig 没有做成一个常驻服务，而是做成配置生成加环境检查的组合。常驻服务虽然切换更丝滑，但会引入额外的进程管理和端口占用问题，对只想安安静静写代码的人来说反而是负担。配置生成的方式更轻，代价是每次切换要重新应用一次配置，但换来的是可审计、可版本控制。

3. 环境准备：Node.js 与 YAML 的安装细节

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

不管你用哪个系统，第一步都是把 Node.js 装对。Windows 用户直接去 Node.js 官网下载 LTS 的 msi 安装包，一路下一步就行，安装时记得勾选“Add to PATH”，否则后面命令行里找不到 node 命令。Ubuntu 用户我更推荐用 NodeSource 的源来装，比系统自带的版本新，命令大致是这样：

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs

装完之后必须验证，别装完就往下走：

node -v npm -v

两个命令都要有输出，且 node 版本建议在 18 以上。如果node -v报“command not found”，说明 PATH 没配好，Windows 重启终端或者手动加环境变量，Ubuntu 检查/usr/bin/node是否存在。

注意：不要同时装多个来源的 Node.js，比如系统 apt 装了一个、nvm 又装了一个，很容易出现node -v和实际运行版本不一致的诡异问题。选定一种方式就坚持用。

3.2 YAML 环境的理解与工具准备

严格来说 YAML 不是需要“安装”的东西，它是一种文件格式。但很多人搜“yaml安装”其实是想要一个能校验 YAML 的工具。我的建议是装一个yaml的 npm 包做命令行校验，或者直接在 VS Code 里装 YAML 插件，写的时候就有缩进高亮和错误提示。

npm install -g yaml

装完之后可以用它来检查配置文件语法：

yaml openrig.yaml

如果文件有问题会直接报出行号和原因，比肉眼一行行看快得多。VS Code 里我常用的是 Red Hat 出的 YAML 插件，它对 Claude Code 配置、Codex 配置这类文件的 schema 支持比较好，能提前发现字段名写错的问题。

3.3 目录结构规划：让配置有地方放

openrig 的配置不建议散落在用户目录各处。我习惯在项目根目录或者用户主目录下建一个统一的.openrig文件夹，里面放openrig.yaml主配置和profiles/子目录存不同场景的配置片段。这样切换场景时只需要换 profile 引用，不用改主文件。

~/.openrig/ ├── openrig.yaml ├── profiles/ │ ├── claude-local.yaml │ ├── codex-cloud.yaml │ └── shared-endpoints.yaml └── logs/

这个结构的好处是端点定义可以抽到shared-endpoints.yaml里复用，Claude Code 和 Codex 引用同一份端点配置，改一处两边都生效。日志目录留着排查cc switch local proxy failed这类问题时看转发记录。

4. openrig.yaml 配置文件的完整写法

4.1 主配置文件的结构设计

一份能跑的 openrig.yaml 大致分四块：runtime 定义运行时、tools 定义要装的 CLI、endpoints 定义模型端点、profiles 定义场景组合。我下面给一份可以直接抄的模板，字段名按常见实践来，你根据自己实际情况改值。

runtime: node: ">=18.0.0" packageManager: npm tools: claude-code: enabled: true package: "@anthropic-ai/claude-code" endpoint: local-qwen codex: enabled: true package: "codex-cli" endpoint: cloud-deepseek endpoints: local-qwen: baseUrl: "http://127.0.0.1:1234/v1" model: "qwen2.5-coder" apiKey: "local" cloud-deepseek: baseUrl: "https://api.deepseek.com/v1" model: "deepseek-coder" apiKey: "${DEEPSEEK_API_KEY}" profiles: default: tools: - claude-code - codex

这里有几个设计点要解释。runtime.node用语义化版本区间而不是固定版本，是为了兼容不同机器上已有的 Node；apiKey用${}引用环境变量而不是写死，避免密钥进版本库；endpoints抽出来单独定义，是为了让多个工具共享。

4.2 端点配置与模型切换的关键字段

端点这块是 openrig 最核心也最容易出错的地方。baseUrl必须指向兼容 OpenAI 接口格式的服务，因为 Claude Code 和 Codex 底层大多按这个格式发请求。本地模型比如通过 LM Studio 起的服务，默认端口常见是 1234，路径是/v1，少写这个/v1就会出现 404 或者endpoint /responses找不到的问题。

model字段要和服务端实际加载的模型名完全一致，大小写都不能错。我见过有人本地加载的是Qwen2.5-Coder-7B，配置里写qwen2.5-coder，结果请求发过去服务端不认，报模型不存在。最稳妥的办法是先 curl 一下服务端的模型列表接口确认名字：

curl http://127.0.0.1:1234/v1/models

返回的id字段是什么，配置里就写什么。

4.3 用 profile 实现 Claude Code 与 Codex 的快速切换

profile 的意义在于把“工具组合 + 端点组合”打包成一个可切换的单元。比如你有一个localprofile 全部指向本地模型，一个cloudprofile 指向云端端点，切换时只需要改主配置里activeProfile的值，或者用命令行参数指定。

activeProfile: local profiles: local: tools: [claude-code, codex] endpoints: claude-code: local-qwen codex: local-qwen cloud: tools: [claude-code, codex] endpoints: claude-code: cloud-deepseek codex: cloud-deepseek

这种写法的好处是切换粒度可控，你可以让 Claude Code 走本地、Codex 走云端，也可以两个都走同一个端点。实际用下来，本地模型响应快但能力有限，云端模型能力强但有延迟和成本，混着用是最务实的。

5. 实操过程：从零到跑通一次完整切换

5.1 安装 Claude Code 与 Codex 的实操步骤

Node.js 就绪之后，装 Claude Code 和 Codex 都是 npm 全局安装。Claude Code 的包名按官方文档来，Codex 的 CLI 包名社区里有几个变体，装之前最好确认一下当前维护的版本。

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

装完分别验证：

claude --version codex --version

如果claude命令找不到，检查 npm 全局 bin 目录是否在 PATH 里。Windows 上通常是%APPDATA%\npm，Ubuntu 上是/usr/local/bin或~/.npm-global/bin。这一步卡住的人特别多，本质都是 PATH 问题，不是安装失败。

提示：如果你在 VS Code 里用 Claude Code，装完 CLI 之后还要在 VS Code 里装对应扩展，然后在设置里指向 CLI 路径。VS Code 配置 Claude Code 时最容易漏的就是这个路径设置。

5.2 应用 openrig 配置并验证端点连通性

配置写完之后不要急着启动工具，先做连通性验证。用 curl 打一下端点，确认能返回模型列表：

curl -s http://127.0.0.1:1234/v1/models | head -20

能返回 JSON 且里面有模型 id，说明端点本身没问题。然后再验证 API key 是否生效，云端端点可以发一个最小的 chat 请求：

curl -s https://api.deepseek.com/v1/chat/completions \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-coder","messages":[{"role":"user","content":"hi"}]}'

这一步能通，后面工具里基本不会因为端点问题报错。如果这一步就失败，问题在端点或密钥，跟 openrig 和工具本身无关，排查范围一下子缩小了。

5.3 切换过程中的现场记录与观察

我第一次做本地到云端的切换时，记录了几个关键观察点。切换后 Claude Code 首次请求会有明显延迟，因为要重新建立连接和加载模型上下文；Codex 在切换端点后如果报the 'gpt-5.6-sol' model is not supported，说明配置里模型名还是旧的，没跟着端点一起换。这个报错信息其实很明确，就是模型名和端点不匹配。

另一个观察是代理层。如果你用了 cc switch 这类本地代理来做端点转发，切换时要确认代理进程有没有重启。我遇到过代理没重启、配置改了但请求还走旧端点的情况，表现为改了配置没效果。后来养成习惯，每次切换后先看代理日志确认请求打到了哪个端点。

tail -f ~/.openrig/logs/proxy.log

日志里能看到实际转发的 URL 和模型名，比猜靠谱得多。

6. 常见报错与排查速查

6.1 安装类报错的处理思路

安装阶段最高频的就是 Node 版本相关报错。error installing 24.21.0: node.js v24.21.0 is not yet released这种，要么是版本号写错，要么是源同步延迟，换成 LTS 版本基本能解决。还有your organization has disabled claude subscription access这类，属于账号权限层面，不是本地环境问题，需要去账号设置里确认订阅状态。

6.2 端点与代理类报错的定位方法

cc switch local proxy failed while handling codex endpoint /responses这个报错我遇到不止一次，根因通常是三类：端点 URL 拼错、代理进程没起来、模型名不匹配。定位顺序建议是先 curl 直连端点，通了再查代理，代理通了再查工具配置。一层层排除，比一上来就改配置高效。

还有一个隐蔽的坑是端口占用。本地模型服务默认端口如果被别的进程占了，服务起不来但报错不明显，表现为连接被拒绝。用lsof -i :1234或者 Windows 的netstat -ano | findstr 1234确认端口状态。

6.3 模型调用类报错的应对

模型调用阶段的报错往往和配置字段强相关。model is not supported是模型名不对，401 unauthorized是密钥问题，404 not found多半是 baseUrl 路径少了/v1。这几个报错信息都很直白，对着配置逐字段核对就行。

我整理了一个排查顺序，实测下来能覆盖八成问题：先确认 Node 版本，再确认 CLI 能启动，再 curl 端点，再看代理日志，最后核对模型名和密钥。这个顺序是从底层往上层走，避免在错误的层面上浪费时间。

注意：改完配置后一定要重新加载，很多工具不会自动监听配置文件变化。Claude Code 和 Codex 都需要重启会话才能读到新配置。

7. 我踩过的坑和几条实用经验

配置文件的编码问题值得单独说。YAML 对 UTF-8 有要求，如果你在 Windows 上用记事本编辑，偶尔会存成带 BOM 的 UTF-8，导致解析时报奇怪的字符错误。我现在的习惯是统一用 VS Code 编辑，右下角确认编码是 UTF-8 无 BOM。

环境变量注入的时机也容易出问题。${DEEPSEEK_API_KEY}这种引用，要求启动工具的那个 shell 里确实有这个变量。如果你在 A 终端 export 了变量，在 B 终端启动工具，是读不到的。要么写进 shell 的启动脚本，要么在同一个终端里操作。

还有一点是关于本地模型的选择。不是所有本地模型都适合做代码助手，有些模型对工具调用格式支持不好，接进 Claude Code 或 Codex 之后会频繁报解析错误。选模型时优先挑明确支持 function calling 的版本，能省掉大量调试时间。

最后分享一个我常用的验证小技巧：配置改完之后，先用一个最简单的 prompt 跑一次，比如让它输出当前目录的文件列表。这个请求链路短、依赖少，能快速验证“配置-端点-模型”整条链路是否通畅。链路通了再去跑复杂任务，排查成本低很多。这套流程用熟之后，换机器、换模型、换工具基本十分钟内能搞定，比每次从头查文档快得多。