企业官网建设流程全解析

1. openrig 到底想解决什么问题

第一次看到 openrig 这个名字，我下意识以为是某个硬件机架项目，毕竟 rig 这个词在无线电、矿业、舞台设备里都指“架子、装置”。但把 openrig 和 Claude Code、Codex、YAML、npm 这几个词放在一起看，方向就很清楚了：它是一套围绕 AI 编程助手做配置编排与运行环境管理的工具思路，核心目标是把散落在各处的模型接入参数、命令行工具配置、项目级规则文件统一收拢到一份可版本化的 YAML 里，再通过 npm 生态分发和调用。

为什么这件事值得单独做一个工具？因为过去一年我在实际项目里反复遇到同一个场景：一个仓库里同时要用 Claude Code 做代码审查、用 Codex 做补全和重构、本地还挂着 LM Studio 跑的小模型做离线兜底。每个工具都有自己的配置文件、自己的环境变量、自己的启动参数，改一个模型端点要在四五个地方同步修改，稍不留神就出现“Claude Code 能跑、Codex 报 endpoint 不匹配”这种割裂状态。openrig 要解决的就是这种多助手、多模型、多项目之间的配置漂移问题。

它适合谁？三类人最直接受益。第一类是同时使用两个以上 AI 编程助手的开发者，尤其是需要在 Claude Code 和 Codex 之间来回切换的人；第二类是需要把 AI 助手配置纳入团队规范的技术负责人，希望新同事 clone 仓库后一条命令就能跑起来；第三类是在本地跑模型、又想让云端助手和本地模型共存的折腾型玩家。哪怕你只是刚装完 npm、还在为 PowerShell 脚本执行策略报错发愁，理解 openrig 的设计思路也能帮你少走很多弯路。

需要先说明的是，openrig 目前并不是一个已经高度标准化的成熟产品，网络上关于它的公开资料相当零散，更多是社区里围绕“如何统一管理 AI 助手配置”衍生出来的一类实践。所以下面我讲的，是基于这类工具最常见的实现方式、结合我自己搭配置管理层的经验做的合理还原，具体到某个版本的字段名可能和你的实际环境有出入，但思路和踩坑点是通用的。

2. 整体设计思路与方案选型拆解

2.1 为什么是 YAML 而不是 JSON 或 TOML

配置格式的选择看着是小事，实际决定了这个工具好不好用。openrig 这类工具几乎都会选 YAML，原因很实在。

JSON 的问题是不支持注释。AI 助手的配置里经常需要标注“这个 key 是临时测试用的”“这个端点下个月要换”，JSON 里你只能靠额外的_comment字段硬塞，读起来很别扭。TOML 虽然支持注释、结构也清晰，但它在表达嵌套的列表套对象时比较啰嗦，而 AI 助手配置恰恰经常是“一个 providers 列表，每个 provider 下面又有 models 列表”这种结构。

YAML 的优势在于缩进即层级，写起来接近自然语言，而且天然支持多文档（用---分隔），可以把“全局默认配置”和“项目覆盖配置”放在同一个文件里。代价是它对缩进极其敏感，一个 Tab 和空格的混用就能让整个文件解析失败。我踩过最典型的一次坑：从网页复制配置片段时带进了全角空格，YAML 解析器直接报mapping values are not allowed here，排查了二十分钟才发现是看不见的字符问题。

提示：写 YAML 时把编辑器的“显示空白字符”打开，并且统一用两个空格缩进，永远不要用 Tab。这一条能省掉你八成的 YAML 报错。

2.2 为什么走 npm 分发

openrig 选择 npm 作为分发渠道，逻辑也很顺。目标用户本身就是开发者，机器上大概率已经有 Node.js 环境；npm 的全局安装和npx临时执行能力，让工具可以做到“不装也能试”。更重要的是，npm 的package.json里可以声明bin字段，把 openrig 注册成一个命令行入口，用户装完直接敲openrig就能用。

但 npm 在国内环境有个老问题：默认源速度慢，安装大包时经常卡住。所以实际使用前，把源换成国内镜像是常规操作。这里给一个我常用的配置方式：

npm config set registry https://registry.npmmirror.com npm config get registry

第二条命令用来确认是否生效。如果你在公司内网，可能还需要额外配置代理相关的环境变量，这个要按你所在网络的实际要求来，不要照搬网上的通用方案。

2.3 核心抽象：把“助手”和“模型”解耦

openrig 设计上最关键的一步，是把**助手（Claude Code、Codex）和模型提供方（云端 API、本地 LM Studio）**拆成两个独立维度。传统做法是把模型信息直接写死在助手的配置里，导致换模型就要改助手配置。解耦之后，配置结构大致长这样：

providers: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder cloud-main: base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} models: - gpt-5.6-sol assistants: claude-code: provider: cloud-main model: gpt-5.6-sol codex: provider: local-lmstudio model: qwen2.5-coder

这样切换模型只需要改assistants下面的一行，providers部分完全不用动。${CLOUD_API_KEY}这种写法是引用环境变量，避免把密钥明文写进版本库——这一点在团队协作里是硬性要求，密钥进了 Git 历史就很难彻底清除。

3. 核心细节解析与实操要点

3.1 环境准备：先把 npm 和 Node 理顺

openrig 依赖 npm 生态，所以第一步是把 Node.js 和 npm 装好、装对。Windows 用户最容易卡在 PowerShell 的脚本执行策略上，报错信息通常是这样的：

npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本

这不是 npm 坏了，而是 PowerShell 默认不允许执行.ps1脚本。解决办法是以管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

RemoteSigned的含义是：本地写的脚本可以直接跑，从网络下载的脚本需要签名。这比直接设成Unrestricted安全，也比Restricted实用。改完之后关掉终端重开，npm -v应该就能正常输出版本号了。

另一个高频问题是“Node 装完了但 npm 不能用”，多半是环境变量 PATH 没配好。检查方法是：

where node where npm

如果node能找到而npm找不到，说明 Node 的安装目录没进 PATH，或者 npm 的全局目录没进 PATH。手动把C:\Program Files\nodejs和%APPDATA%\npm加进系统 PATH 即可。

3.2 安装 openrig 与验证

环境理顺后，安装本身很简单：

npm install -g openrig openrig --version

如果不想全局安装，可以用npx openrig临时执行。全局安装的好处是任何目录下都能调用，坏处是升级时要记得手动更新。卸载全局包的命令也顺手记一下：

npm uninstall -g openrig

有时候卸载会残留，尤其是 Windows 上文件被占用时。遇到EBUSY或EPERM报错，先关掉所有可能占用该文件的终端和编辑器，再重试。

注意：全局安装的包如果装到了需要管理员权限的目录，后续升级可能失败。建议把 npm 的全局目录改到用户目录下，避免权限问题。

3.3 配置文件的位置与优先级

openrig 这类工具通常支持多级配置，优先级从高到低一般是：命令行参数 > 项目目录下的配置文件 > 用户主目录下的全局配置 > 内置默认值。项目级配置一般放在仓库根目录，命名可能是openrig.yaml或.openrig/config.yaml，具体以你用的版本为准。

这个优先级设计的意义在于：团队可以把项目级配置提交到仓库，保证所有人用同一套模型和端点；个人则可以在全局配置里放自己的密钥和本地模型地址，不污染团队配置。我一般会在.gitignore里加上全局配置的路径，防止误提交。

配置加载失败时，openrig 通常会打印它实际读取了哪些文件。养成看启动日志的习惯，能快速定位“为什么我的配置没生效”——十有八九是文件放错了目录，或者文件名拼写不对。

3.4 助手接入的关键参数

把 Claude Code 或 Codex 接到 openrig 管理的模型上，核心是三个参数：base_url、api_key、model。

base_url要指向兼容 OpenAI 接口规范的端点。本地 LM Studio 默认监听http://127.0.0.1:1234/v1，云端服务则用各自提供的地址。这里最常见的坑是多写或少写/v1。有些服务要求 URL 以/v1结尾，有些则要求不带，写错了就会返回 404 或者endpoint /responses not found这类错误。

api_key对本地模型通常随便填一个非空字符串即可，因为本地服务一般不校验。但有些客户端会检查这个字段是否存在，留空反而报错，所以填not-needed是稳妥做法。

model字段必须和提供方实际暴露的模型名完全一致。比如你本地加载的是qwen2.5-coder，配置里写成qwen-coder就会报模型不存在。这个错误信息有时候很隐晦，表现为“模型不支持”而不是“模型不存在”，容易误导排查方向。

4. 实操过程与核心环节实现

4.1 从零搭一套可用的配置

假设你的目标是：Claude Code 走云端模型，Codex 走本地 LM Studio，两个助手共享同一份 provider 定义。完整流程如下。

第一步，确认本地模型服务已经跑起来。打开 LM Studio，加载一个模型，启动本地服务器，然后在浏览器或命令行验证端点可达：

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

能返回模型列表，说明本地服务正常。这一步不能省，很多人配置写完发现连不上，最后查出来是本地服务根本没启动。

第二步，创建项目级配置文件openrig.yaml：

version: 1 providers: local: base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder cloud: base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} models: - gpt-5.6-sol assistants: claude-code: provider: cloud model: gpt-5.6-sol context_window: 1000000 codex: provider: local model: qwen2.5-coder

第三步，设置环境变量。Linux 和 macOS 用export CLOUD_API_KEY=你的密钥，Windows PowerShell 用$env:CLOUD_API_KEY="你的密钥"。想持久化的话，Linux 写进~/.bashrc，Windows 用系统设置里的环境变量界面。

第四步，验证配置：

openrig validate openrig list

validate检查语法和字段合法性，list列出当前生效的助手和模型映射。两个命令都通过，基本就可以用了。

4.2 参数计算：上下文窗口怎么填

context_window这个参数容易被忽略，但填错会直接导致长文件处理失败。它的单位是 token，不是字符。粗略换算：英文大约 1 token 对应 4 个字符，中文大约 1 token 对应 1.5 到 2 个字符。

假设你的模型实际支持 128K 上下文，但你要留出空间给输出，那么输入侧最多用 100K 左右比较稳妥。配置里填的应该是模型的总窗口，而不是你打算用的输入长度。如果填得比模型实际能力大，请求会在服务端被截断或直接报错；填得太小，又浪费了模型能力。

我一般的做法是：先查模型官方文档确认总窗口，然后按总窗口的 75% 到 80% 设置实际使用的输入上限，剩下的留给输出和系统提示词。

4.3 多助手切换的实操记录

配置好之后，切换助手就是改一行的事。但实际用起来还有几个细节值得说。

Claude Code 和 Codex 对配置的读取时机不同。有的工具在启动时读一次配置，运行中改文件不生效，必须重启；有的支持热重载。我遇到过改了配置但行为没变的情况，最后发现是旧进程还在后台跑着。所以改完配置后，养成“先确认没有残留进程，再重新启动”的习惯。

另外，两个助手对系统提示词的处理方式不一样。Claude Code 倾向于把项目规则文件的内容拼进系统提示，Codex 可能更依赖仓库里的约定文件。如果你在 openrig 里统一管理了规则文件路径，要注意不同助手对文件格式的要求可能不同，别指望一份文件两边都完美适配。

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

5.1 高频报错速查表

5.2 几个文档里不会写的坑

第一个坑是环境变量的作用域。在 Windows 上，你用图形界面改了系统环境变量，但已经打开的终端不会自动刷新，必须重开终端才生效。我见过有人改了变量、重启了 openrig，还是报密钥缺失，最后发现是终端没重开。

第二个坑是配置文件的编码。YAML 文件必须是 UTF-8 无 BOM 编码。Windows 记事本默认可能存成带 BOM 的 UTF-8，某些解析器会因此报错。用 VS Code 或 Notepad++ 保存时注意选“UTF-8 无 BOM”。

第三个坑是本地模型的并发限制。LM Studio 默认可能只允许一个并发请求，如果你同时开 Claude Code 和 Codex 都指向本地模型，第二个请求会排队甚至超时。解决办法是在 LM Studio 设置里调高并发数，或者让两个助手错开使用。

第四个坑是npm 的 peer dependency 警告。安装时经常看到npm warn eresolve overriding peer dependency，大多数情况下可以忽略，但如果工具启动就崩，就要认真看这个警告涉及的包版本是否冲突。必要时用npm ls 包名查看依赖树。

5.3 排查思路的通用套路

遇到问题，我的排查顺序固定是四步：先看报错原文，别急着搜；再确认配置加载了哪个文件；然后单独测试端点连通性；最后才怀疑工具本身。这个顺序能解决九成问题，因为绝大多数故障出在配置和环境，而不是工具代码。

具体到端点测试，curl是最可靠的手段。它能排除掉助手客户端的所有干扰，直接告诉你服务端返回什么。如果curl通而助手不通，问题一定在助手配置；如果curl也不通，问题在服务端或网络。

6. 配置管理的进阶玩法

6.1 用多文档 YAML 分离环境

YAML 的多文档特性很适合管理多环境配置。你可以把开发、测试、生产三套配置写在同一个文件里，用---分隔，然后通过命令行参数选择加载哪一段。这样比维护三个独立文件更不容易漏改。

# 开发环境 environment: dev providers: local: base_url: http://127.0.0.1:1234/v1 --- # 生产环境 environment: prod providers: cloud: base_url: https://api.example.com/v1

6.2 把配置纳入版本控制

团队协作时，项目级配置应该进 Git，但密钥绝对不能进。做法是把密钥全部写成环境变量引用，然后在仓库里放一份.env.example说明需要哪些变量。新同事 clone 之后，照着示例配好自己的环境变量就能跑。

我还会在 CI 里加一步openrig validate，确保提交的配置语法正确。这一步能拦住很多低级错误，比如有人手滑删了个冒号。

6.3 配置的向后兼容

工具升级时配置格式可能变化。稳妥做法是在配置里写version字段，工具根据版本号决定用哪套解析逻辑。你自己维护配置时，也建议在文件顶部写一行注释记录最后修改日期和修改人，方便回溯。

7. 我个人的几点体会

折腾 openrig 这类配置管理工具，最大的收获不是省了多少时间，而是把隐性的环境依赖显性化了。以前 AI 助手的配置散落在各处，出问题只能靠记忆排查；现在所有东西都在一份 YAML 里，谁改了什么一目了然。

另一个体会是，本地模型和云端模型混用是趋势，但两者的行为差异比想象中大。本地模型响应快、隐私好，但在复杂推理上往往不如云端大模型；云端模型能力强，但有延迟和成本。openrig 这种解耦设计让你能按任务类型灵活分配，比如简单补全走本地、复杂重构走云端。

最后分享一个小技巧：给每个 provider 起名字时，用“用途+位置”的格式，比如local-fast、cloud-strong，比provider1、provider2直观得多。配置是给人读的，命名清晰能省下大量回头查文档的时间。