企业官网建设流程全解析

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 rig 这个词在英文里本来就有“装配、设备”的意思。但如果你最近在折腾 Claude Code、Codex 这类命令行 AI 编程工具，大概率已经在某些讨论里见过它。简单说，openrig 是一个围绕 AI 编程助手做“统一接入与配置管理”的开源思路或工具集，核心目标是把 Claude Code、Codex 这类工具的模型接入、端点配置、环境变量管理用一套相对标准化的方式管起来，而不是每换一个模型就手动改一遍配置文件。

它解决的问题很具体。现在用 Claude Code 的人越来越多，用 Codex 的人也不少，但这两套工具各自有自己的配置方式、自己的环境变量、自己的端点约定。你想让 Claude Code 走本地模型，得改一套东西；想让 Codex 接第三方兼容端点，又得改另一套东西。来回切换的时候，配置文件改来改去，很容易把之前能用的配置覆盖掉，最后自己也记不清哪个版本是对的。openrig 想做的就是把这层配置抽象出来，用 YAML 描述“我要用哪个模型、走哪个端点、带哪些参数”，然后由工具去生成或注入对应的配置。

适合谁来参考这份内容？三类人最合适。第一类是已经在用 Claude Code 或 Codex，但每次换模型都要翻文档、改环境变量的开发者；第二类是想在本地或内网环境里跑 AI 编程助手，需要把端点指向自己服务的人；第三类是对 Node.js 工具有一定了解，愿意花半小时把配置理顺，之后长期省事的人。如果你完全没接触过命令行工具，也没关系，我会把 Node.js 安装、YAML 怎么写这些基础环节都拆开讲。

提示：openrig 目前更像是一种配置管理思路的集合，不同人手里的实现可能不完全一样。下面讲的是基于常见实践整理出来的通用方案，你落地时以自己实际拿到的仓库说明为准。

2. 为什么需要一层配置抽象

2.1 Claude Code 和 Codex 各自的配置痛点

Claude Code 的配置主要围绕环境变量和它自己的设置文件展开。你想让它走非默认端点，通常要设置类似ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY这样的变量，或者写进它的配置文件里。Codex 这边则是另一套，它有自己的端点约定，比如处理/responses这类路径时的行为，还有模型名称校验，像gpt-5.6-sol这种不被支持的模型名会直接报错。两套工具的环境变量名不一样，配置文件位置不一样，连“模型不支持”这种报错的触发条件都不一样。

痛点就在这里。你如果同时用这两个工具，或者经常在“官方端点”和“第三方兼容端点”之间切换，就会陷入一种重复劳动：改 Claude Code 的配置，测试；改 Codex 的配置，测试；想切回去，又得把之前的配置找回来。更麻烦的是，有些配置是写在 shell 的启动脚本里的，改错了会影响整个终端会话，排查起来很费时间。

2.2 用 YAML 做统一描述的好处

YAML 最大的好处是可读性好，而且结构清晰。你可以在一个文件里描述多个“配置档”，每个档位对应一套模型和端点组合。比如一个档位叫local，指向本地跑的模型服务；另一个档位叫remote，指向一个兼容端点。切换的时候只需要告诉工具“用 local 这个档”，剩下的环境变量注入、配置文件生成都由工具完成。

这种做法的另一个好处是可版本管理。你把 YAML 文件放进 Git，每次改动都有记录，哪天配置坏了，直接回滚到上一个提交就行。相比之下，手动改环境变量很难追溯，改完就忘了改了什么。YAML 还能写注释，你可以标注每个端点的用途、申请方式、注意事项，团队协作的时候别人一看就懂。

2.3 Node.js 在其中的角色

openrig 这类工具大概率是用 Node.js 写的，因为 Claude Code 和 Codex 本身都跟 Node.js 生态关系密切。Node.js 在这里扮演的是“运行时”的角色，工具本身是一段 JavaScript 代码，需要 Node.js 来执行。你安装 Node.js，本质上是在给这些工具准备一个能跑起来的环境。

这里有个常见的坑：Node.js 版本不是越新越好。有些工具对 Node.js 版本有要求，太新的版本可能还没被支持，安装时会报node.js v24.21.0 is not yet released or is not available这类错误。稳妥的做法是装 LTS 版本，也就是长期支持版，稳定性和兼容性都更好。Node.js 官网下载页面会明确标出 LTS 版本，选那个就行。

3. 环境准备：Node.js 与基础工具安装

3.1 Node.js 安装的正确姿势

Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包，一路下一步就行。安装完成后打开 PowerShell 或 CMD，输入node -v和npm -v，能看到版本号就说明装好了。macOS 用户可以用官网的 pkg 安装包，也可以用 Homebrew，命令是brew install node@lts。Ubuntu 用户建议用 NodeSource 的源来装，比系统自带的版本新，具体命令是先加源再apt install nodejs。

装完之后有一个关键检查：确认npm的全局安装目录在 PATH 里。Windows 上一般是%APPDATA%\npm，macOS 和 Linux 上一般是/usr/local/bin或~/.npm-global/bin。如果全局安装的工具命令找不到，多半是这里没配好。你可以用npm config get prefix看当前的前缀路径，然后把这个路径下的bin目录加到 PATH 里。

注意：不要用sudo npm install -g在 macOS 和 Linux 上装全局包，容易造成权限混乱。正确做法是配置一个用户级的全局目录，或者用 nvm 这类版本管理工具来管理 Node.js。

3.2 YAML 文件的基本写法

YAML 的语法看着简单，但有几个地方特别容易写错。第一是缩进必须用空格，不能用 Tab，而且同一层级缩进要一致。第二是冒号后面要跟一个空格，key: value是对的，key:value在某些解析器里会被当成一个整体。第三是字符串如果包含特殊字符，最好用引号包起来，单引号双引号都行，但双引号里支持转义。

一个典型的 openrig 配置大概长这样：

profiles: local: provider: local base_url: "http://127.0.0.1:1234" api_key: "not-needed" model: "local-model" remote: provider: compatible base_url: "https://api.example.com" api_key: "your-key-here" model: "gpt-5.6-sol" default_profile: local

这个结构里，profiles下面挂了两个档位，每个档位有自己的base_url、api_key和model。default_profile指定默认用哪个。你实际拿到的配置字段名可能不一样，但思路是相通的：把变化的部分抽出来，用键值对描述。

3.3 安装 openrig 或同类工具

如果 openrig 是以 npm 包的形式发布，安装命令通常是npm install -g openrig。装完之后用openrig --help看它支持哪些子命令。常见的子命令包括init（生成初始配置）、use（切换档位）、apply（把配置写入目标工具）、list（列出所有档位）。如果它不是 npm 包，而是一个仓库，那就先git clone下来，然后npm install装依赖，再用node直接跑入口文件。

安装过程中如果遇到网络问题导致包下载失败，可以换一个 npm 镜像源。命令是npm config set registry https://registry.npmmirror.com，这个镜像在国内访问速度比较稳定。装完之后如果想换回官方源，把 registry 设回https://registry.npmjs.org就行。

4. 核心配置解析与实操要点

4.1 端点与模型名称的对应关系

配置里最容易出错的地方是端点路径和模型名称的匹配。Claude Code 和 Codex 对端点的要求不一样。Claude Code 通常期望一个兼容 Anthropic 接口的端点，而 Codex 走的是另一套约定，处理/responses这类路径时有自己的逻辑。如果你把 Claude Code 的端点直接填给 Codex，很可能报cc switch local proxy failed while handling codex endpoint /responses这类错误。

模型名称也是同理。Codex 对模型名有校验，像gpt-5.6-sol这种不在支持列表里的名字会直接报the 'gpt-5.6-sol' model is not supported when using codex。解决办法是查一下你用的端点支持哪些模型名，填一个明确支持的。如果你用的是第三方兼容端点，通常它的文档里会列出可用模型名，照着填就行。

4.2 环境变量注入的时机

openrig 这类工具在“切换档位”时，通常要做一件事：把 YAML 里的配置转换成目标工具能识别的环境变量或配置文件。这里有个时机问题。如果你是在当前 shell 里直接跑 Claude Code，那环境变量需要在启动 Claude Code 之前就设好。如果 openrig 是通过生成一个包装脚本来实现，那这个脚本里会先export变量再调用目标命令。

实操中我建议用“生成配置文件”而不是“改当前 shell 环境变量”的方式。原因是改当前 shell 的环境变量只对当前会话有效，新开一个终端就没了，容易让人困惑“为什么昨天能用今天不行”。生成配置文件则是持久化的，目标工具每次启动都会读，行为一致。

4.3 多档位切换的实操心得

我自己的做法是至少保留三个档位：一个local指向本地模型服务，一个remote指向常用的兼容端点，一个official指向官方端点。日常写代码用local，速度快、不消耗额度；需要更强模型的时候切remote；排查问题的时候切official做对照。切换命令就是openrig use local这种，一秒钟的事。

这里有个细节：切换之后最好验证一下当前生效的配置。可以加一个openrig current之类的命令，或者直接看目标工具的配置文件内容。我踩过的坑是切换命令执行了，但因为权限问题配置文件没写进去，工具还在用旧配置，排查了半天才发现是文件权限的事。所以切换后验证这一步不能省。

提示：把 YAML 配置文件纳入 Git 管理，但api_key这类敏感信息不要直接写进去。可以用环境变量引用，比如api_key: "${MY_API_KEY}"，然后在 shell 里设这个变量。这样配置文件可以放心提交。

5. 完整实操流程：从零到能用

5.1 第一步：确认 Node.js 环境可用

打开终端，跑node -v。如果提示命令找不到，说明 Node.js 没装好或者 PATH 没配。回到第 3 节的安装步骤重新来一遍。如果版本号低于 18，建议升级到 LTS 版本，因为很多现代工具要求 Node.js 18 以上。升级可以用 nvm，命令是nvm install --lts然后nvm use --lts。

5.2 第二步：安装并初始化 openrig

假设是 npm 包，执行npm install -g openrig。装完后跑openrig init，它会在当前目录或用户目录下生成一个初始的 YAML 配置文件。打开这个文件，你会看到一些示例档位。把示例里的base_url、api_key、model换成你自己的。如果你用的是本地模型服务，base_url一般填http://127.0.0.1:端口号，api_key随便填一个非空字符串就行，本地服务通常不校验。

5.3 第三步：配置 Claude Code 档位

在 YAML 里加一个专门给 Claude Code 用的档位。关键字段是base_url和api_key，对应 Claude Code 需要的环境变量。有些实现里还会有一个tool: claude-code的标记，告诉 openrig 这个档位是给谁用的。配好之后执行openrig apply claude-code，它会把这套配置写入 Claude Code 能读到的位置。

5.4 第四步：配置 Codex 档位

Codex 的档位单独配。注意model字段要填 Codex 支持的模型名，别填它不认的。base_url要符合 Codex 的端点约定，如果你的端点不支持/responses路径，Codex 可能会报错。配好后执行openrig apply codex。如果报模型不支持，就换一个模型名再试。

5.5 第五步：验证与切换

两个工具都配好之后，分别启动它们，看是否能正常对话。Claude Code 启动后随便问一句，Codex 同理。如果都能正常返回，说明配置生效了。之后切换档位就用openrig use 档位名，然后重启对应的工具。注意有些工具是启动时读配置，运行中改配置不生效，所以切换后要重启。

# 查看当前所有档位 openrig list # 切换到 local 档 openrig use local # 把当前档位应用到 Claude Code openrig apply claude-code # 把当前档位应用到 Codex openrig apply codex

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

6.1 报错“模型不支持”怎么处理

这个报错在 Codex 上最常见。原因是你填的模型名不在 Codex 的支持列表里。解决办法是查你所用端点的文档，找一个明确支持的模型名。如果你用的是第三方兼容端点，它可能支持很多模型，但 Codex 只认其中一部分。实在找不到就先用一个已知支持的模型名测试，确认链路通了再换。

6.2 端点处理失败怎么排查

cc switch local proxy failed while handling codex endpoint /responses这类错误，说明请求打到了端点，但端点不认识这个路径或这个请求格式。排查顺序是：先确认base_url填对了，没有多斜杠或少斜杠；再确认端点本身是否支持 Codex 的请求格式；最后看是不是代理层做了路径重写导致路径变了。如果是本地代理，检查代理的转发规则。

6.3 组织策略限制导致的订阅访问问题

有些环境下会提示your organization has disabled claude subscription access for claude code，意思是组织层面禁用了订阅方式的访问。这种情况通常需要用 API 密钥方式而不是订阅方式，或者联系管理员确认策略。这不是配置能绕过的，属于权限层面的限制。

6.4 常见问题速查表

6.5 我踩过的几个坑

第一个坑是 YAML 缩进用了 Tab，解析器直接报错，但报错信息很模糊，只说“解析失败”，没说是哪一行。后来用了一个在线 YAML 校验工具才定位到。第二个坑是api_key里带了空格，YAML 把它当成了字符串的一部分，导致认证失败。第三个坑是切换档位后忘了重启工具，一直以为配置没生效，其实是工具还在用启动时读的旧配置。

提示：改完 YAML 之后，先跑一遍 YAML 语法校验，再执行 apply。很多工具自带openrig validate之类的命令，没有的话用在线校验工具也行。这一步花十秒钟，能省掉后面十分钟的排查。

7. 进阶用法与扩展思路

7.1 把配置纳入团队协作

团队里每个人用的模型和端点可能不一样，但配置结构可以统一。做法是把 YAML 里的敏感信息用环境变量占位，配置文件本身提交到仓库。每个人在自己机器上设好自己的环境变量，然后openrig apply一下就行。这样新人入职的时候，clone 仓库、装 Node.js、设环境变量、apply，四步就能跑起来，不用挨个问“你那个端点怎么配的”。

7.2 结合 VS Code 使用

VS Code 里可以用集成终端跑 Claude Code 或 Codex。如果你在 VS Code 里装了相关插件，配置读取的路径可能和独立终端不一样。这时候要确认 openrig 生成的配置文件放对了位置。有些插件会读工作区下的配置文件，有些读用户目录下的，具体看插件文档。我的做法是两边都配一份，或者用符号链接把工作区配置指向用户目录配置，避免不一致。

7.3 本地模型接入的注意事项

本地跑模型服务的时候，base_url通常是http://127.0.0.1:端口。注意不要写成localhost，有些环境下localhost解析会有问题，用127.0.0.1更稳。另外本地服务的并发能力有限，如果你同时开 Claude Code 和 Codex 都指向同一个本地服务，可能会排队等待。这种情况可以给两个工具配不同的本地服务实例，或者错开使用。

7.4 配置的备份与迁移

换电脑的时候，YAML 配置文件直接拷过去就行，但环境变量要重新设。我习惯把环境变量的设置也写成一个脚本，放在配置文件旁边，换机器的时候一起拷过去，跑一下脚本就恢复环境。脚本里不要硬编码密钥，而是从系统密钥管理或者加密文件里读，这样更安全。

8. 一些个人体会

这套东西用下来，最大的感受是“配置即代码”这个思路确实省事。以前换模型要翻半天文档，现在改一行 YAML 就行。但前提是 YAML 本身要写对，缩进、引号、空格这些细节不能马虎。我现在的习惯是每次改完配置先校验语法，再 apply，再重启工具验证，三步走完才放心。

另外一点是不要贪多。档位不用配太多，三四个够用了。配太多自己都记不住哪个是哪个，反而增加心智负担。命名也要清晰，local、remote、official这种一看就懂，别用a、b、c这种。最后，敏感信息一定不要写进 YAML 提交到仓库，用环境变量引用，这是底线。