企业官网建设流程全解析

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，我下意识以为是某个硬件机架项目，毕竟 rig 在英文里常指设备支架、钻井平台这类实体。但翻了一圈社区讨论和仓库结构之后才反应过来，这是一个围绕 AI 编程助手做配置编排的开源工具，核心解决的是 Claude Code、Codex 这类命令行 AI 助手在不同项目之间切换时配置散乱、环境不一致的问题。

说白了，openrig 做的事情可以用一句话概括：把 AI 编程助手的配置、模型接入、项目上下文、工具链参数，统一收拢到一份可版本管理的 YAML 文件里，然后用一条命令完成环境装配。你可以把它理解成 AI 编程助手的 dotfiles 管理器加环境编排器的结合体。

为什么这个东西现在值得聊？因为 Claude Code 和 Codex 这两个工具在过去一年里几乎成了后端和全栈开发者的标配，但它们的配置方式各有各的脾气。Claude Code 依赖 settings.json 和 CLAUDE.md，Codex 有自己的 config 目录和 endpoint 配置，两边都要管模型来源、代理地址、项目级指令、权限白名单。项目一多，配置就开始打架。我自己手上同时维护四个项目，两个用 Claude Code 跑本地模型，两个用 Codex 接远程 API，每次切项目都要手动改配置，改错一次就要排查半天。

openrig 就是冲着这个痛点来的。它适合三类人：一是同时使用多个 AI 编程助手的开发者，二是需要在团队内统一 AI 助手配置的技术负责人，三是想把本地模型和云端模型混着用、需要频繁切换 endpoint 的折腾党。哪怕你只是刚装完 Claude Code、还在研究 npm 全局包怎么配的新手，理解 openrig 的设计思路也能帮你把环境理清楚。

2. 核心设计思路与方案选型拆解

2.1 为什么选 YAML 作为配置载体

openrig 用 YAML 而不是 JSON 或 TOML，这个选择背后有很实际的考量。JSON 不支持注释，而 AI 助手的配置里经常需要标注"这个 endpoint 是本地 LM Studio 的""这个模型名对应 DeepSeek 的哪个版本"，没有注释会非常痛苦。TOML 虽然支持注释，但嵌套结构写起来啰嗦，尤其是当你要描述多个 provider、多个 model、多个项目 profile 的时候，TOML 的层级表达会变得很长。

YAML 的优势在于它天然适合表达层级化的配置树，而且支持锚点和引用，这一点对 openrig 特别关键。比如你定义了三个项目都用同一个本地模型 endpoint，就可以用锚点复用，不用三处重复写。我实测下来，一个中等复杂度的 openrig 配置大概在 80 到 150 行 YAML 之间，如果用 JSON 写同样的内容，至少要膨胀到 250 行以上，而且没法加注释。

提示：YAML 对缩进极其敏感，建议统一用两个空格，绝对不要混用 Tab 和空格。我见过太多人因为一个 Tab 导致整个配置解析失败，排查半小时才发现是缩进问题。

2.2 配置分层：全局层、项目层、会话层

openrig 的配置模型是三层结构，这个设计直接决定了它的灵活性。全局层放在用户主目录下，定义所有项目共享的东西，比如默认模型、通用权限、日志级别。项目层放在项目根目录，定义这个项目特有的东西，比如项目上下文文件路径、专属的模型参数、需要排除的目录。会话层是运行时临时覆盖，比如你今天想临时切到另一个模型跑一次测试，不用改任何文件，命令行参数直接覆盖。

这三层的优先级是会话层大于项目层大于全局层。为什么这么设计？因为实际开发中最高频的需求就是"大部分时候用默认配置，偶尔临时改一下"。如果只有全局和项目两层，临时改配置就得动文件，改完还得记得改回来，很容易忘。会话层解决了这个问题。

2.3 与 Claude Code、Codex 的对接方式

openrig 本身不替代 Claude Code 或 Codex，它是一个编排层，负责在启动这些工具之前把配置准备好。具体做法是：openrig 读取自己的 YAML 配置，然后根据目标工具生成对应的配置文件，或者通过环境变量注入参数，最后拉起 Claude Code 或 Codex 的进程。

对 Claude Code 来说，openrig 主要处理的是 settings.json 的生成和 CLAUDE.md 的路径映射。对 Codex 来说，重点是 endpoint 配置和模型参数的注入。这里有个细节值得说：Codex 的 endpoint 配置格式和 Claude Code 不完全一样，openrig 在中间做了一层适配，把统一的配置模型翻译成各自需要的格式。这个适配层是 openrig 最有价值的部分之一，因为它把"不同工具配置格式不同"这个脏活揽下来了。

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

3.1 配置文件的最小可用结构

一个能跑起来的最小 openrig 配置大概长这样：

version: 1 defaults: provider: local model: qwen2.5-coder-7b providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed remote: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} projects: my-app: path: ~/work/my-app provider: local context_files: - CLAUDE.md - docs/architecture.md

这个结构里，version 是配置格式版本，defaults 是默认值，providers 定义模型来源，projects 定义项目级覆盖。注意 api_key 用了环境变量引用语法，这是为了避免密钥硬编码进配置文件。openrig 支持${VAR_NAME}这种引用方式，运行时从环境变量读取。

3.2 provider 配置的关键参数

provider 是 openrig 配置里最容易出错的部分，因为不同模型服务的兼容性差异很大。核心参数有这么几个：

base_url 结尾带不带 /v1 这个问题坑过很多人。OpenAI 兼容协议的标准是 base_url 应该包含 /v1，然后客户端会自动拼接 /chat/completions。但有些本地服务实现不规范，有的要求带 /v1，有的要求不带。我的经验是先用 curl 手动测一下，确认完整的请求路径是什么，再填进配置。

3.3 项目上下文文件的组织方式

Claude Code 和 Codex 都支持项目级上下文注入，但方式不同。Claude Code 读 CLAUDE.md，Codex 读自己的指令文件。openrig 的 context_files 字段让你用统一的方式声明项目上下文，然后由 openrig 负责把它们映射到各自工具需要的位置。

这里有个实操心得：上下文文件不要写太长。我一开始把整个架构文档塞进 CLAUDE.md，结果每次请求都带上几千 token 的上下文，响应变慢不说，模型还容易被无关信息干扰。后来改成只放最关键的约定，比如代码风格、目录结构、禁止使用的库，详细文档放在 docs 目录里按需引用。上下文文件控制在 500 行以内比较合适。

3.4 环境变量与密钥管理

openrig 支持三种密钥来源：直接写在配置里（不推荐）、环境变量引用、外部密钥文件。生产环境或者团队协作场景，强烈建议用环境变量。具体做法是在 shell 的配置文件里 export，或者用 direnv 这类工具做项目级环境变量管理。

注意：不要把包含真实密钥的 openrig 配置提交到 Git 仓库。建议在 .gitignore 里排除本地覆盖文件，仓库里只保留模板文件，用 .example 后缀区分。

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

4.1 环境准备：Node 与 npm 的正确配置

openrig 通过 npm 分发，所以第一步是把 Node 环境弄好。这一步看起来简单，但热词里大量出现 npm 相关的报错，说明很多人卡在这里。

Windows 上最常见的报错是"无法加载文件 npm.ps1，因为在此系统上禁止运行脚本"。这是 PowerShell 的执行策略问题，解决办法是以管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

执行完输入 Y 确认即可。这个操作只影响当前用户，不会降低系统整体安全性。

另一个高频问题是 npm 全局包安装后命令找不到，这通常是 PATH 没配好。npm 全局包的安装位置可以用npm config get prefix查看，然后确认这个路径在系统 PATH 里。Windows 上默认是%APPDATA%\npm，macOS 和 Linux 上通常是/usr/local或~/.npm-global。

国内网络环境下，npm 官方源速度可能不理想，可以切换镜像源：

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

切换后可以用npm config get registry确认。如果之后要发布自己的包，记得临时切回官方源，或者用--registry参数指定。

4.2 安装 openrig 与验证

环境准备好之后，安装就一条命令：

npm install -g openrig

安装完成后验证：

openrig --version openrig doctor

openrig doctor是自检命令，会检查 Node 版本、配置文件位置、已安装的 AI 助手工具、环境变量等。这个命令非常有用，配置出问题时先跑它，能省很多排查时间。

如果安装过程中遇到npm warn eresolve overriding peer dependency这类警告，一般不影响使用，是依赖树里有版本冲突但 npm 自动解决了。如果遇到cannot find module '@npmcli/config'这种错误，通常是 npm 自身损坏，可以尝试npm install -g npm@latest重装 npm。

4.3 编写第一份 openrig 配置

安装完成后，在项目根目录创建openrig.yaml。我建议从最小配置开始，跑通了再逐步加东西。第一步只配一个 provider 和一个项目：

version: 1 defaults: provider: local model: qwen2.5-coder-7b providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: local timeout: 120 projects: demo: path: . provider: local

然后运行：

openrig validate

这个命令会检查配置语法和字段合法性。如果报错，根据提示逐项修正。验证通过后，用：

openrig launch claude

或

openrig launch codex

来启动对应的工具。openrig 会在启动前把配置翻译成目标工具需要的格式。

4.4 多项目切换的实际操作

假设你手上有三个项目，两个用本地模型，一个用远程 API。配置可以这样组织：

version: 1 defaults: provider: local model: qwen2.5-coder-7b providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: local remote: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} timeout: 300 projects: project-a: path: ~/work/project-a provider: local project-b: path: ~/work/project-b provider: local model: deepseek-coder-v2 project-c: path: ~/work/project-c provider: remote model: gpt-4o

切换项目时，进入对应目录直接运行openrig launch claude，openrig 会自动匹配当前目录属于哪个项目，加载对应配置。如果目录匹配不上，可以用--project参数手动指定。

4.5 与本地模型服务的对接细节

用 LM Studio 或类似工具跑本地模型时，有几个参数需要特别注意。首先是上下文长度，本地模型的上下文窗口通常比云端小，如果 openrig 配置里的 max_tokens 设得太大，请求会直接失败。其次是并发数，本地服务一般只支持单并发，如果同时开多个 AI 助手实例，会互相抢资源。

我的做法是在 openrig 配置里给本地 provider 单独设一组保守参数：

providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: local timeout: 180 max_tokens: 2048 extra: temperature: 0.2 top_p: 0.9

temperature 调低是因为写代码场景需要确定性输出，0.2 左右比较合适。top_p 保持 0.9 是常规做法。这些参数会透传给模型服务。

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

5.1 配置解析失败类问题

YAML 解析失败是最常见的问题，表现是 openrig 启动时报语法错误。排查顺序是：先看缩进，再看特殊字符，最后看编码。缩进问题前面说过了，统一两个空格。特殊字符主要是冒号和引号，YAML 里字符串包含冒号时最好用引号包起来。编码问题在 Windows 上偶发，确保文件保存为 UTF-8 无 BOM 格式。

5.2 模型连接失败类问题

连接失败的表现是启动后请求超时或返回 401、404。排查步骤：

1. 用 curl 直接测 base_url 是否可达
2. 确认 api_key 是否正确注入（echo $REMOTE_API_KEY）
3. 确认模型名和服务端加载的模型名完全一致
4. 检查 base_url 结尾的 /v1 是否需要

我遇到过一次 404，排查半天发现是 base_url 多写了一个斜杠，变成http://127.0.0.1:1234/v1//chat/completions。这种问题只能靠仔细核对。

5.3 工具启动后配置未生效

有时候 openrig 启动成功，但 Claude Code 或 Codex 用的还是旧配置。这通常是缓存问题。Claude Code 会缓存 settings.json，Codex 也有自己的配置缓存目录。解决办法是找到对应工具的缓存位置清掉，或者用 openrig 的--force-reload参数强制刷新。

5.4 常见问题速查表

5.5 几个踩过的坑

第一个坑是环境变量在 Windows 和 Unix 下的写法差异。openrig 的${VAR}语法在两个平台都能用，但如果你在 Windows 的 cmd 里设置环境变量，语法是set VAR=value，PowerShell 里是$env:VAR="value"，bash 里是export VAR=value。搞混了就会导致变量读不到。

第二个坑是项目路径用了相对路径。openrig 的 projects.path 建议用绝对路径或者~开头的路径，相对路径的解析基准有时候不符合预期。我一开始写path: ./my-app，结果 openrig 从全局配置目录去解析，找不到项目。

第三个坑是同时装了多个版本的 Node。用 nvm 管理 Node 版本时，全局包是跟着 Node 版本走的。切换 Node 版本后，之前装的 openrig 就找不到了，需要重新安装。这个不是 bug，是 nvm 的设计，但很容易让人困惑。

6. 进阶用法与扩展思路

6.1 团队配置共享

团队协作场景下，可以把 openrig 配置拆成两部分：共享部分提交到仓库，个人部分放在本地覆盖文件里。共享部分包含 provider 定义（不含密钥）、项目结构、通用参数。个人部分包含密钥、个人偏好的模型、本地路径。openrig 支持配置合并，本地覆盖文件的优先级高于共享配置。

具体做法是在仓库里放openrig.yaml，在 .gitignore 里加openrig.local.yaml。启动时 openrig 会自动合并两个文件，本地文件里的同名字段覆盖共享文件。

6.2 多模型混合编排

openrig 支持在项目级别指定不同的模型做不同的事。比如代码生成用一个模型，代码审查用另一个模型。这个通过 profile 机制实现：

projects: my-app: path: ~/work/my-app profiles: coding: provider: local model: qwen2.5-coder-7b review: provider: remote model: gpt-4o default_profile: coding

启动时用--profile review切换。这个用法在需要高质量审查但想省本地资源的时候特别有用。

6.3 与 CI 流程的结合

openrig 的配置是纯文本的，天然适合版本管理。在 CI 流程里可以用 openrig 来确保构建环境使用的 AI 助手配置和开发环境一致。具体做法是在 CI 脚本里加一步openrig validate，配置有问题直接让构建失败，避免因为配置漂移导致的诡异问题。

6.4 配置模板化

如果你经常创建新项目，可以准备一套 openrig 配置模板，新项目直接复制。模板里把项目名、路径这些变量化，用脚本生成具体配置。我用一个简单的 shell 脚本做这件事，输入项目名和路径，自动生成对应的 openrig.yaml 片段并追加到主配置里。

7. 我个人在实际操作中的几点体会

折腾 openrig 这段时间，最大的感受是配置管理这件事，前期多花十分钟理清楚，后期能省几小时排查。我一开始图省事，所有配置都堆在一个文件里，项目多了之后改一处影响一片，后来拆成全局加项目两层，清晰多了。

另一个体会是不要过度配置。openrig 支持的字段很多，但真正高频用到的就那么几个：provider、model、base_url、context_files。其他参数等真正需要的时候再加，一开始全配上反而容易出错。

最后分享一个小技巧：openrig 的 doctor 命令可以加--verbose参数输出详细诊断信息，包括每个配置项的来源（是全局配置还是项目配置还是环境变量）。排查配置覆盖问题时这个特别有用，能一眼看出某个值到底是从哪来的。