企业官网建设流程全解析

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

第一次看到openrig这个词，我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的“装备架”。事实也确实八九不离十。在当下这个 AI 编程助手满天飞的阶段，claude code、codex这类命令行智能体（CLI Agent）已经成了不少开发者日常写代码、改 bug、跑脚本的标配工具。但问题也随之而来：每个工具都有自己的配置格式、自己的模型接入方式、自己的环境变量命名习惯。你今天用claude code接本地模型，明天想换成codex接另一家 API，后天又想在 VS Code 里同时管理好几套配置——光是来回改配置文件就能把人折腾到怀疑人生。

openrig要干的事情，本质上就是把这些零散的、各自为政的 AI 编程工具配置，统一收拢到一个可管理、可切换、可复用的“装备架”上。它不是一个模型，也不是一个 IDE 插件，而更像是一层配置编排层：用 YAML 描述你有哪些工具、每个工具用哪个模型、走哪个端点、带哪些参数，然后由它来负责把这些配置正确地“喂”给对应的 CLI 工具。你可以把它理解成 AI 编程工具界的“docker-compose”——只不过它编排的不是容器，而是claude code、codex这些智能体的运行配置。

这个项目适合谁？三类人最该关注。第一类是多工具重度用户，同时用claude code和codex，甚至还在试各种新出的 CLI Agent，配置管理已经成了负担。第二类是本地模型玩家，比如用 LM Studio、Ollama 跑本地模型，想让claude code调用本地模型，但被端点配置、模型名映射搞得头大。第三类是团队协作场景，需要把一套统一的 AI 工具配置分发给多个成员，保证大家用的模型、参数、端点一致，避免“你那边能跑我这边报错”的经典问题。

关键词里出现的yaml、node.js也印证了这个定位：openrig大概率是一个基于 Node.js 运行时的 CLI 工具，用 YAML 作为配置描述语言。YAML 的好处是结构清晰、人类可读、支持注释，比 JSON 适合写配置，比 TOML 在嵌套结构上更灵活。Node.js 则保证了跨平台（Windows、macOS、Linux 都能跑）和与前端工具链的天然亲和。接下来我会从设计思路、核心配置、实操流程、踩坑排查几个维度，把这个“装备架”拆开讲透。

2. 整体设计思路：为什么是 YAML + Node.js 这套组合

2.1 配置编排层的核心价值在哪里

要理解openrig的设计，先得理解它面对的是一个什么样的混乱现场。claude code有自己的配置文件，通常在用户目录下的某个隐藏文件夹里，格式可能是 JSON；codex也有自己的一套，环境变量名、端点路径、认证方式都可能不一样。更麻烦的是，这些工具在迭代过程中配置格式还会变。你今天照着某篇教程配好了，明天工具升级，配置项改名了，又得重新查文档。

openrig的思路是抽象出一层中间配置。你不再直接去改每个工具的原生配置，而是只维护一份openrig的 YAML 文件。这份文件里描述的是“意图”——我要用哪个模型、走哪个端点、给哪个工具用。至于怎么把这个意图翻译成claude code能认的格式、codex能认的格式，那是openrig的事。这就好比你写 Dockerfile 描述的是“我要一个什么环境”，而不是手动去敲一堆apt-get和export。

这种设计带来的直接好处有三个。第一是切换成本极低：想从模型 A 换到模型 B，改一行 YAML 就行，不用去翻每个工具各自的配置文档。第二是配置可版本化：一份 YAML 可以提交到 Git，团队共享，出问题能追溯。第三是降低认知负担：你只需要学一套配置语法，就能管理多个工具，不用为每个工具单独记一套配置规则。

2.2 为什么选 YAML 而不是 JSON 或 TOML

配置文件格式的选择看着是小事，实际上直接影响日常使用体验。JSON 的问题是不支持注释，而且嵌套深了之后括号对不齐，人眼很难快速定位。你想想，一个配置文件里要描述三四个工具、每个工具有五六个参数，用 JSON 写出来就是一大坨花括号，改的时候得小心翼翼数逗号。TOML 在简单配置上很优雅，但一旦涉及到嵌套的对象数组（比如“多个工具，每个工具多个模型”），表达起来就有点别扭。

YAML 在这两者之间找到了平衡。它用缩进表达层级，视觉上清爽；支持#注释，可以给每个配置项写说明；支持锚点和引用，能复用重复的配置块。对于openrig这种“描述多个工具、多个模型、多个端点”的场景，YAML 的表达力刚好够用，又不会过于复杂。当然 YAML 也有它的坑，最著名的就是缩进必须用空格不能用 Tab，以及某些特殊字符需要引号包裹，这些后面讲实操的时候会具体说。

2.3 Node.js 运行时带来的跨平台与生态优势

选 Node.js 作为运行时，我认为是openrig一个很务实的决定。首先，claude code和codex这类工具本身就是 Node.js 生态的产物，用 Node.js 来编排它们，在进程调用、环境变量传递、标准输入输出处理上天然顺畅。其次，Node.js 的跨平台能力成熟，Windows 上用npm install -g装全局 CLI 已经是标准操作，macOS 和 Linux 更不用说。第三，Node.js 生态里有大量现成的库可以处理 YAML 解析、命令行参数解析、文件监听，开发效率高。

从使用者角度看，这意味着你只需要装一个 Node.js 环境（建议 LTS 版本），就能通过 npm 把openrig装成全局命令，然后在任何项目目录下用。不需要额外装 Python、不需要配 Java 环境，对前端和全栈开发者尤其友好。关键词里反复出现的node.js安装、node.js lts下载、node.js官网下载也说明，很多人的第一步卡点就在环境准备上，这个后面会专门讲。

3. 核心配置解析：一份 openrig.yaml 应该长什么样

3.1 配置文件的基本骨架与字段含义

虽然openrig的具体字段命名可能随版本变化，但基于这类配置编排工具的通用设计，一份典型的openrig.yaml大致会包含以下几个顶层区块。我按最常见的实践给你梳理一个骨架，你在实际使用时对照官方文档微调字段名即可。

# openrig.yaml version: 1 # 定义可用的模型端点 providers: local-lmstudio: type: openai-compatible baseUrl: http://localhost:1234/v1 apiKey: not-needed remote-deepseek: type: openai-compatible baseUrl: https://api.deepseek.com/v1 apiKey: ${DEEPSEEK_API_KEY} # 定义模型别名，映射到具体 provider models: fast-local: provider: local-lmstudio model: qwen2.5-coder-7b deep-reason: provider: remote-deepseek model: deepseek-chat # 定义工具及其使用的模型 tools: claude-code: model: deep-reason env: ANTHROPIC_BASE_URL: ${provider.baseUrl} codex: model: fast-local env: OPENAI_BASE_URL: ${provider.baseUrl}

这个骨架里，providers描述“去哪里调用模型”，models描述“用哪个模型”，tools描述“哪个工具用哪个模型”。三层分离的好处是：换端点不用动模型定义，换模型不用动工具定义。比如你本地 LM Studio 的端口从 1234 改成 8080，只需要改providers里的一行，所有引用它的模型和工具自动生效。

${DEEPSEEK_API_KEY}这种写法是环境变量插值，目的是避免把密钥明文写进配置文件。这一点非常重要，因为配置文件很可能要提交到 Git 或者分享给同事，密钥泄露的后果不用我多说。openrig在读取配置时会从系统环境变量里取值填充，这样配置文件本身可以安全地版本化。

3.2 provider、model、tool 三层抽象的设计逻辑

为什么非要拆成三层？直接用“工具 → 端点 + 模型名”两层不行吗？行，但会失去灵活性。我举个实际场景你就明白了。假设你有两个工具claude code和codex，它们都想用同一个本地模型。如果只有两层，你得在两个工具下面各写一遍端点地址和模型名，重复且容易不一致。有了models这一层，你定义一个fast-local模型别名，两个工具都引用它，改的时候只改一处。

再比如，同一个端点下可能有多个模型（一个快的、一个强的），你想让codex用快的做补全、claude code用强的做重构。三层结构下，你定义两个 model 别名指向同一个 provider，然后分别分配给两个工具，清晰明了。这种“关注点分离”的设计在配置管理里是经典套路，Kubernetes 的Service/Deployment/Pod也是类似思路。

还有一点值得说：type: openai-compatible这个字段。现在大量本地模型服务和第三方 API 都兼容 OpenAI 的接口格式，所以只要标成openai-compatible，openrig就知道用统一的协议去调用，不用为每个服务写适配器。这也是为什么claude code 调用lmstudio的本地模型这类需求能通过配置解决——LM Studio 暴露的就是 OpenAI 兼容接口。

3.3 环境变量插值与密钥管理的最佳实践

密钥管理是配置编排里最容易出事的地方。我见过太多人把 API Key 直接写在配置文件里，然后不小心提交到公开仓库，第二天收到账单警告。openrig支持环境变量插值，正确的做法是：

• 配置文件里只写${VAR_NAME}占位符
• 真实的密钥放在系统环境变量或.env文件里
• .env文件加入.gitignore，绝不提交

在 Windows 上设置环境变量可以用setx命令或者系统设置界面；在 macOS/Linux 上可以在~/.bashrc或~/.zshrc里export。如果你用.env文件，openrig通常会自动加载当前目录下的.env，这样每个项目可以有独立的密钥配置，互不干扰。

注意：环境变量插值的语法在不同工具里可能是${VAR}也可能是$VAR，甚至有的用{{VAR}}。以openrig官方文档为准，别想当然。我踩过的坑就是照着别的工具语法写，结果插值没生效，工具拿着字面量${DEEPSEEK_API_KEY}去请求，报了个莫名其妙的认证错误，排查了半天才发现是语法问题。

4. 实操全流程：从零把 openrig 跑起来

4.1 环境准备：Node.js 安装与版本选择

第一步永远是环境。openrig基于 Node.js，所以你得先有 Node.js。这里有个关键选择：装 LTS 版本还是最新版？我的建议是无脑选 LTS。LTS（Long Term Support）是长期支持版，稳定、bug 少、生态兼容性好。最新版虽然有一些新特性，但可能和某些依赖不兼容，尤其是你还要同时跑claude code、codex这些工具，它们对 Node.js 版本可能有各自的要求，LTS 是最安全的交集。

安装方式按平台分：

• Windows：去 Node.js 官网下载 LTS 的.msi安装包，双击一路下一步。安装完成后打开 PowerShell 或 CMD，输入node -v和npm -v验证。如果提示“不是内部或外部命令”，说明 PATH 没配好，重启终端或者手动把 Node.js 安装目录加进系统 PATH。
• macOS：推荐用nvm（Node Version Manager）管理，命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash，然后nvm install --lts。用 nvm 的好处是可以在多个 Node.js 版本间切换，遇到某个工具要求特定版本时不用重装。
• Linux（Ubuntu/Debian）：同样推荐 nvm，步骤和 macOS 一样。如果不想用 nvm，可以用sudo apt install nodejs npm，但 apt 源里的版本可能偏旧，建议还是 nvm。

装完之后验证一下：node -v应该输出类似v20.x.x或v22.x.x的版本号。如果版本太老（比如 v14 以下），某些现代工具会跑不起来，这时候用 nvm 升级一下。

提示：关键词里有个error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava，这是典型的版本号写错导致的。Node.js 的版本号是主版本.次版本.修订号，24.21.0 这种组合可能根本不存在。装的时候认准官网或 nvm 给出的实际可用版本，别手敲一个想当然的版本号。

4.2 安装 openrig 并初始化第一个配置

Node.js 就绪后，安装openrig通常就是一条 npm 命令：

npm install -g openrig

-g表示全局安装，这样在任何目录下都能用openrig命令。装完后输入openrig --version验证。如果提示命令找不到，检查 npm 的全局 bin 目录是否在 PATH 里。可以用npm config get prefix查看全局安装路径，然后把这个路径下的bin（Windows 是根目录）加进 PATH。

接下来初始化配置。大多数这类工具会提供一个init命令：

openrig init

它会在当前目录生成一个openrig.yaml模板文件。你也可以手动创建这个文件，把上一节讲的骨架填进去。初始化之后，用openrig validate之类的命令检查配置语法是否正确——YAML 的缩进错误很隐蔽，有个校验命令能省很多事。

4.3 接入本地模型：以 LM Studio 为例的完整配置

本地模型接入是很多人用openrig的核心诉求。以 LM Studio 为例，完整流程是这样的：

1. 打开 LM Studio，在“Developer”或“Local Server”标签页启动服务，默认端口 1234。确认它暴露的是 OpenAI 兼容接口，地址通常是http://localhost:1234/v1。
2. 在 LM Studio 里加载一个模型，比如qwen2.5-coder-7b，记下模型标识符。
3. 在openrig.yaml里配置 provider 和 model：

providers: local-lmstudio: type: openai-compatible baseUrl: http://localhost:1234/v1 apiKey: lm-studio models: local-coder: provider: local-lmstudio model: qwen2.5-coder-7b tools: claude-code: model: local-coder

4. 运行openrig apply或类似命令，让配置生效。这一步openrig会把你的意图翻译成claude code能认的环境变量或配置文件。
5. 启动claude code，测试它是否能正常调用本地模型。

这里有个细节：apiKey字段对本地模型通常是摆设，LM Studio 不校验，但有些客户端库要求这个字段非空，所以随便填一个占位符就行，比如lm-studio。

4.4 多工具切换：claude code 与 codex 共存配置

同时用claude code和codex是openrig的典型场景。配置上，你只需要在tools区块下分别定义：

tools: claude-code: model: deep-reason env: ANTHROPIC_BASE_URL: ${provider.baseUrl} ANTHROPIC_API_KEY: ${provider.apiKey} codex: model: fast-local env: OPENAI_BASE_URL: ${provider.baseUrl} OPENAI_API_KEY: ${provider.apiKey}

注意不同工具用的环境变量名不一样。claude code认的是ANTHROPIC_前缀，codex认的是OPENAI_前缀。openrig的价值就在于帮你处理这些差异——你在 YAML 里写一次，它负责翻译成各自需要的格式。切换的时候，用openrig use claude-code或openrig use codex之类的命令激活对应配置，或者它可能通过生成不同的配置文件来实现隔离。

实操心得：多工具共存时，最容易出问题的是端口冲突和环境变量污染。比如你之前手动export过一个OPENAI_BASE_URL，openrig又设了一个，到底哪个生效取决于加载顺序。建议在切换工具前，先echo一下相关环境变量，确认没有残留的旧值。我吃过这个亏，明明配置改了，工具却还在用旧端点，查了半天才发现是 shell 里有个手动 export 的变量在捣乱。

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

5.1 配置不生效：从加载顺序到缓存机制

“我明明改了配置，怎么没生效？”这是最高频的问题。排查思路按以下顺序来：

第一，确认配置文件被正确加载。openrig可能支持多级配置（全局配置、项目配置、环境变量覆盖），加载顺序决定了最终生效的值。用openrig config show或类似命令打印出实际生效的配置，和你以为的配置对比。这一步能解决八成问题。

第二，检查环境变量残留。前面提过，手动 export 的变量可能覆盖配置文件。在终端里env | grep -i相关前缀，看看有没有意外设置。

第三，确认工具是否重启。很多 CLI 工具在启动时读取配置，运行中不会热加载。改完配置后要重启工具进程。

第四，检查缓存。有些工具会缓存认证信息或端点配置，存在用户目录的隐藏文件夹里。如果配置改了还不生效，试试清缓存或者删掉工具自己的配置文件，让openrig重新生成。

5.2 模型调用报错：端点、模型名与认证的三重检查

调用模型时报错，错误信息往往很模糊，比如401 Unauthorized、404 Not Found、model not supported。按这三项逐一排查：

关键词里有个the 'gpt-5.6-sol' model is not supported when using codex，这就是典型的模型名不匹配。codex可能对模型名有白名单校验，你配了一个它不认识的模型名，它就拒绝。解决办法是查codex支持的模型列表，用列表里的名字，或者看openrig是否提供了模型名映射功能。

5.3 组织策略限制与订阅访问问题

关键词里出现了your organization has disabled claude subscription access for claude code，这是企业环境下的常见限制。如果你的账号属于某个组织，管理员可能关闭了通过订阅方式访问claude code的权限。这种情况下，配置层面能做的有限，你需要：

• 确认是否可以使用 API Key 方式而非订阅方式访问
• 联系组织管理员确认策略
• 如果是个人使用，确认账号类型和订阅状态

这类问题本质上是权限问题，不是配置问题，openrig帮不了你绕过策略，但可以帮你快速切换到其他可用的模型端点，保证工作流不中断。这也是配置编排层的价值——一条路走不通，改一行配置换条路。

5.4 YAML 语法坑：缩进、引号与特殊字符

YAML 看着简单，坑不少。最常见的三个：

缩进必须用空格，不能用 Tab。这是 YAML 的铁律。很多编辑器默认 Tab 缩进，写出来的 YAML 解析直接报错。建议在编辑器里设置 YAML 文件用 2 空格缩进。

含特殊字符的值要加引号。比如baseUrl: http://localhost:1234/v1里的冒号，如果不加引号，YAML 可能把http当成键、//localhost...当成值。稳妥做法是给所有 URL 加引号：baseUrl: "http://localhost:1234/v1"。

布尔值和字符串的歧义。yes、no、on、off在 YAML 里可能被解析成布尔值。如果你想要字符串"no"，必须加引号。模型名或参数里出现这些词时要特别注意。

提示：写完 YAML 后用在线 YAML 校验器或者openrig validate过一遍，能提前发现大部分语法问题。别等到运行时才报错，那时候错误信息往往指向别处，排查成本高得多。

6. 进阶玩法与个人经验补充

6.1 配置模板化与团队共享

当你把openrig.yaml调通之后，下一步就是团队共享。做法是把配置文件提交到项目仓库，但密钥部分用环境变量占位，每个成员在自己机器上设置环境变量。这样新人入职只需要：装 Node.js、装openrig、设置环境变量、openrig apply，四步就能拥有和你一致的 AI 工具配置。

更进一步，你可以准备多份配置模板：一份接本地模型的（适合离线开发）、一份接云端 API 的（适合需要强模型的场景）、一份接公司内部端点的。用openrig的配置切换功能，在不同场景间快速切换。这比每个人各自维护一套配置要可靠得多。

6.2 与 VS Code 的协同配置

关键词里vscode配置claude code、claude code for vs code、vscode接入claude code出现频率很高，说明很多人是在 VS Code 里用这些工具的。openrig和 VS Code 的协同点在于：VS Code 里的终端会继承系统环境变量，所以openrig设置的环境变量在 VS Code 终端里也能生效。如果你在 VS Code 里装了claude code插件，插件读取的也是同一套环境变量，配置一次两边通用。

需要注意的是，VS Code 有时会缓存终端环境。改完环境变量后，重启 VS Code 或者开一个新终端，确保新变量被加载。如果插件有自己的配置文件，确认它没有覆盖openrig设置的值。

6.3 我踩过的几个真实坑

最后分享几个我在配置这类工具时踩过的坑，都是文档里不会写的。

坑一：端口被占用但不报错。本地模型服务启动时如果端口被占用，有些服务会静默失败或者换端口，但你的配置还指向旧端口。表现就是连接超时。养成习惯：启动本地服务后先curl一下确认可达，再启动 AI 工具。

坑二：模型加载慢导致首次请求超时。本地大模型首次加载可能要几十秒，而 AI 工具的默认超时可能只有 10 秒。表现是第一次请求失败，第二次就好了。解决办法是在配置里调大超时时间，或者先手动预热模型。

坑三：不同工具的模型名大小写敏感。有的服务模型名区分大小写，Qwen2.5-Coder和qwen2.5-coder是两个不同的东西。配置时直接从服务端的模型列表里复制粘贴，别手敲。

坑四：环境变量在 GUI 应用里不生效。如果你在 VS Code 的图形界面里启动工具，它可能不继承 shell 里 export 的变量。解决办法是把变量写进系统级环境变量，或者在 VS Code 的settings.json里配置terminal.integrated.env。

这套东西调通之后，你会发现管理多个 AI 编程工具从“每个都要单独折腾”变成了“改一行 YAML 的事”。openrig这类配置编排工具的价值，不在于它做了什么惊天动地的事，而在于它把重复的、易错的、分散的配置工作收敛到了一处。对于同时用好几个 CLI Agent 的人来说，省下的时间和避免的抓狂，远比学习一套新配置语法的成本高。