企业官网建设流程全解析

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，我下意识以为是某个硬件机架项目，毕竟 rig 这个词在无线电、矿机、测试台架这些圈子里太常见了。但把 openrig 和 Claude Code、Codex、YAML、Node.js 这几个词摆在一起看，方向就清楚了：这是一个围绕 AI 编程助手做本地配置编排的工具，核心工作是把 Claude Code、Codex 这类命令行 AI 编码代理的接入参数、模型端点、代理规则用 YAML 统一管理起来，再通过 Node.js 运行时把配置注入到对应的工具里。

说白了，openrig 解决的是一个很具体的痛点。现在用 Claude Code 或者 Codex 的人越来越多，但这两个工具各自的配置方式完全不一样：Claude Code 走的是自己的 settings 体系，Codex 走的是 config.toml 加环境变量那一套，如果你还想在两者之间切换模型供应商、切换本地模型、切换不同的 API 端点，每次都要手动改配置文件、改环境变量、重启终端。openrig 想做的事情就是把这些散落在各处的配置收拢到一份 YAML 里，用一套统一的描述方式去驱动多个 AI 编码工具。

它适合谁？三类人最需要。第一类是同时用 Claude Code 和 Codex 的开发者，手上有多套模型接入方案，来回切换很烦。第二类是想把本地模型（比如通过 LM Studio 跑起来的模型）接进 Claude Code 的人，需要处理端点映射和协议转换。第三类是在团队里做开发环境标准化的人，希望把 AI 编码工具的配置纳入版本管理，而不是每个人各配各的。

我自己的判断是，openrig 这类工具的价值不在于它多复杂，而在于它把"配置"这件事从"手工活"变成了"可复现的工程产物"。这一点在多人协作或者多机环境下尤其明显。

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

2.1 为什么用 YAML 做配置层

选 YAML 而不是 JSON 或者 TOML，这个决定背后有很实际的考量。JSON 不支持注释，而 AI 编码工具的配置里有大量需要说明的地方，比如某个端点为什么这么写、某个模型别名对应哪个实际模型，这些都需要注释。TOML 虽然支持注释，但嵌套结构写起来比较啰嗦，尤其是当你要描述多个工具、多个供应商、多个模型映射的时候，TOML 的表格语法会让人写得很累。

YAML 的优势在于层级表达自然，缩进即结构，写多供应商多模型的配置时阅读体验最好。而且 YAML 在 DevOps 圈子里已经是事实标准，Kubernetes、Ansible、GitHub Actions 都在用，开发者对它没有学习成本。openrig 选择 YAML，本质上是在降低用户的配置门槛。

但 YAML 也有坑，最大的问题就是缩进敏感和类型推断。比如on、yes、no这些词在 YAML 1.1 里会被解析成布尔值，如果你把模型名写成no，就会出问题。还有端口号如果写成8080没问题，但写成08080就可能被当成八进制。这些细节后面在实操部分会展开讲。

2.2 Node.js 作为运行时的合理性

openrig 用 Node.js 做运行时，这个选择我觉得是权衡之后的最优解。原因有几个：

第一，Claude Code 本身就是 Node.js 生态的产物，它是通过 npm 分发的，安装方式就是npm install -g。Codex 虽然有自己的分发渠道，但在很多场景下也是通过 npm 或者 Node 工具链来管理的。openrig 用 Node.js 写，能直接复用这套生态，不需要用户额外装 Python 或者 Go 运行时。

第二，Node.js 处理 JSON 和 YAML 的能力很成熟，js-yaml、yaml这些库稳定可靠，读写配置文件、做 schema 校验都很方便。

第三，Node.js 的跨平台支持好，Windows、macOS、Linux 上行为一致，这对于一个需要覆盖多平台的配置工具来说很重要。你在 Windows 上写的配置，拿到 Ubuntu 上应该能直接用，Node.js 能保证这一点。

当然，Node.js 也有它的问题，最主要的就是版本管理。不同项目依赖不同的 Node 版本是常态，openrig 如果对 Node 版本有要求，用户就得用 nvm 或者 fnm 来切换。这一点在实际使用中会成为一个高频问题，后面会专门讲。

2.3 统一配置驱动多工具的核心逻辑

openrig 最核心的设计是"一份配置，多个目标"。它的工作流程大致是这样的：

1. 读取用户写的 openrig.yaml
2. 解析出每个工具（Claude Code、Codex）的配置段
3. 根据配置段生成对应工具能识别的配置文件格式
4. 把生成的文件写到工具期望的位置
5. 必要时设置环境变量或者启动代理进程

这个流程的关键在于"格式转换"和"位置映射"。Claude Code 期望的配置格式和 Codex 期望的格式不一样，openrig 要在中间做翻译。同时，不同操作系统上配置文件的存放位置也不一样，Windows 在%APPDATA%下，macOS 和 Linux 在~/.config或者~/.claude下，openrig 要能正确识别。

这种设计的好处是用户只需要学一套配置语法，坏处是 openrig 必须紧跟上游工具的变化。Claude Code 和 Codex 都在快速迭代，配置格式随时可能变，openrig 的维护压力不小。这是所有做"配置抽象层"的工具都要面对的问题。

3. 环境准备与依赖安装实操

3.1 Node.js 版本选择与安装

openrig 对 Node.js 版本有要求，我实测下来建议用 Node.js 20 LTS 或者 22 LTS。不要用太新的版本，比如 24.x，因为有些依赖库还没跟上，会出现error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类报错。也不要用过老的版本，18 以下很多现代语法不支持。

安装方式按平台来：

Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包，一路下一步就行。安装完之后打开 PowerShell 或者 CMD，输入node -v和npm -v确认版本。如果显示的不是你刚装的版本，说明 PATH 里有多个 Node，需要用where node查一下路径。

macOS 用户我强烈建议用 nvm 或者 fnm 来管理 Node 版本，不要直接用官网 pkg 安装。因为 macOS 上权限问题比较多，用版本管理器可以避免EACCES错误。安装 nvm 的命令是：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

装完之后nvm install 20然后nvm use 20。

Ubuntu 用户可以用 NodeSource 的源来装：

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

装完同样用node -v验证。

注意：如果你之前用 apt 装过 nodejs，先sudo apt remove nodejs卸掉，否则会出现两个 Node 打架的情况。

3.2 Claude Code 与 Codex 的安装确认

openrig 本身不负责安装 Claude Code 和 Codex，它只负责配置。所以在用 openrig 之前，你得先确保这两个工具已经装好了。

Claude Code 的安装：

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

装完之后claude --version能输出版本号就说明 OK。如果提示your organization has disabled claude subscription access for claude code，那是账号权限问题，不是安装问题，需要找管理员开通。

Codex 的安装方式取决于你用的版本。如果是 CLI 版本，通常也是通过 npm 或者官方安装包。装完之后codex --version验证。

提示：Claude Code 和 Codex 都建议装在全局，不要装在项目本地，否则 openrig 在生成配置时可能找不到可执行文件路径。

3.3 openrig 的获取与初始化

openrig 的获取方式一般是 clone 仓库或者通过 npm 安装。假设是通过 npm：

npm install -g openrig

装完之后在项目目录下执行初始化：

openrig init

这个命令会生成一份openrig.yaml模板文件。如果你不想用模板，也可以手动创建。初始化之后你会得到一个类似这样的结构：

version: 1 tools: claude-code: enabled: true provider: anthropic model: claude-sonnet-4-20250514 codex: enabled: true provider: openai model: gpt-5.6-sol

这份配置就是 openrig 的核心，后面所有的操作都围绕它展开。

4. openrig.yaml 配置详解与参数计算

4.1 配置文件整体结构

openrig.yaml 的结构设计是分层的，顶层是版本号和工具列表，每个工具下面有自己的配置段。我建议按这个顺序组织：

version: 1 defaults: timeout: 30000 retry: 2 providers: anthropic: base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY openai: base_url: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY local: base_url: http://127.0.0.1:1234/v1 api_key_env: LOCAL_API_KEY tools: claude-code: enabled: true provider: anthropic model: claude-sonnet-4-20250514 env: ANTHROPIC_BASE_URL: ${providers.anthropic.base_url} codex: enabled: true provider: openai model: gpt-5.6-sol env: OPENAI_BASE_URL: ${providers.openai.base_url}

这个结构的好处是 providers 和 tools 分离，多个工具可以复用同一个 provider 定义。比如你既想让 Claude Code 用本地模型，又想让 Codex 用本地模型，只需要在 providers 里定义一次 local，然后在两个工具里都引用它。

4.2 provider 段的参数含义

provider 段描述的是模型服务的接入信息，核心参数有这几个：

• base_url：API 端点地址。这个地址决定了请求发到哪里。如果你用官方服务，就填官方地址；如果你用本地模型，就填本地地址，比如 LM Studio 默认的http://127.0.0.1:1234/v1。
• api_key_env：API key 从哪个环境变量读取。openrig 不会把 key 明文写在 YAML 里，而是通过环境变量注入，这是安全实践。
• headers：额外的请求头。有些第三方服务需要特定的 header，比如自定义的认证头或者版本头。
• timeout：请求超时时间，单位毫秒。默认 30000 也就是 30 秒，如果模型响应慢可以调大。

这里有个容易踩的坑：base_url的结尾要不要带/v1。不同服务的约定不一样，OpenAI 兼容接口通常要求带/v1，但有些代理服务不需要。我的经验是，先按服务商文档来，如果报 404 就试着加或者去掉/v1。

4.3 模型映射与别名机制

openrig 支持模型别名，这个功能在多模型切换场景下非常实用。你可以在配置里定义别名：

models: fast: provider: local model: qwen2.5-coder-7b strong: provider: anthropic model: claude-sonnet-4-20250514

然后在工具里引用别名：

tools: claude-code: model: fast

这样你切换模型的时候只需要改一处，不用去每个工具里改。而且别名让配置的可读性更好，fast比qwen2.5-coder-7b直观多了。

注意：别名不能和实际模型名冲突，否则 openrig 解析时会优先当成别名处理，导致找不到模型。

4.4 环境变量注入与优先级

openrig 在生成配置时会把 provider 里的信息转换成环境变量注入到工具的运行环境里。这里有一个优先级问题需要搞清楚：

1. 工具自身配置文件里的设置优先级最高
2. openrig 注入的环境变量次之
3. 系统全局环境变量优先级最低

也就是说，如果 Claude Code 自己的 settings.json 里已经写了 base_url，那 openrig 注入的就不会生效。所以用 openrig 之前，建议先把工具自身的配置文件清理干净，避免冲突。

5. 完整实操流程：从零到跑通

5.1 第一步：确认 Node 环境

先跑一遍：

node -v npm -v

确认 Node 是 20 或 22 LTS。如果版本不对，用 nvm 切换：

nvm install 20 nvm use 20

Windows 用户如果没有 nvm，可以去下载 nvm-windows，安装后同样用nvm use 20切换。

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

npm install -g openrig openrig init

初始化完成后检查生成的 openrig.yaml，确认路径和内容。

5.3 第三步：配置 provider 和 tool

根据你的实际情况修改 openrig.yaml。如果你用官方服务，填官方 base_url；如果你用本地模型，填本地地址。API key 通过环境变量设置：

export ANTHROPIC_API_KEY=your_key_here export OPENAI_API_KEY=your_key_here

Windows PowerShell 用：

$env:ANTHROPIC_API_KEY="your_key_here"

5.4 第四步：应用配置

openrig apply

这个命令会读取 openrig.yaml，生成各工具需要的配置文件，并写入到正确的位置。执行完之后你会看到类似这样的输出：

[openrig] applying configuration... [openrig] claude-code: wrote ~/.claude/settings.json [openrig] codex: wrote ~/.codex/config.toml [openrig] done.

5.5 第五步：验证配置生效

启动 Claude Code：

claude

然后在里面问一个简单问题，看是否能正常返回。如果返回了，说明配置生效。Codex 同理，跑codex然后测试。

如果报错，先看错误信息里的端点地址是不是你配置的那个。如果端点不对，说明配置没写进去，检查 openrig apply 的输出。

5.6 第六步：切换模型测试

修改 openrig.yaml 里的 model 字段，换成另一个模型，再跑一次openrig apply，重启工具，看是否切换成功。这一步能验证 openrig 的配置驱动能力是否正常工作。

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

6.1 配置不生效的排查顺序

配置不生效是最常见的问题，排查顺序建议这样：

1. 确认 openrig apply 执行成功，没有报错
2. 确认生成的配置文件路径正确，用cat或者编辑器打开看看内容
3. 确认工具读取的是这个路径的配置，有些工具支持多路径，可能读的是另一个
4. 确认环境变量已经设置，用echo $ANTHROPIC_API_KEY检查
5. 重启工具，很多工具只在启动时读配置

6.2 端点连接失败的典型原因

端点连接失败通常有这几个原因：

6.3 YAML 语法错误的快速定位

YAML 语法错误往往报错信息不直观。我常用的定位方法是：

openrig validate

这个命令会做语法校验并指出错误行号。如果没有这个命令，可以用 Python 快速验证：

python3 -c "import yaml; yaml.safe_load(open('openrig.yaml'))"

报错会指出具体行号和问题类型。

6.4 多工具配置冲突的处理

如果你同时用 Claude Code 和 Codex，而且它们都读同一个环境变量，就会冲突。比如两个工具都读OPENAI_API_KEY，但你想让它们用不同的 key。解决办法是在 tool 段里单独覆盖：

tools: claude-code: env: OPENAI_API_KEY: ${CLAUDE_OPENAI_KEY} codex: env: OPENAI_API_KEY: ${CODEX_OPENAI_KEY}

这样每个工具读自己的 key，互不干扰。

6.5 版本升级后的配置迁移

Claude Code 和 Codex 升级后配置格式可能变，openrig 也需要跟着升级。升级前建议先备份 openrig.yaml：

cp openrig.yaml openrig.yaml.bak

然后升级 openrig：

npm update -g openrig

升级后跑openrig validate检查配置是否还兼容，不兼容的话按提示修改。

7. 进阶用法与个人经验

7.1 把 openrig.yaml 纳入版本管理

我强烈建议把 openrig.yaml 提交到 Git 仓库，但 API key 不要写进去。用环境变量引用，然后在 README 里说明需要设置哪些环境变量。这样团队里每个人 clone 下来，设置好自己的 key，跑一次openrig apply就能得到一致的开发环境。

7.2 多环境配置切换

如果你有多个环境（比如公司内网和家里），可以用多个配置文件：

openrig apply --config openrig.work.yaml openrig apply --config openrig.home.yaml

或者用环境变量控制：

providers: anthropic: base_url: ${ANTHROPIC_BASE_URL:-https://api.anthropic.com}

这样默认用官方地址，设置了环境变量就用环境变量的值。

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

把本地模型接入 Claude Code 或 Codex 时，最大的问题是协议兼容性。Claude Code 期望的是 Anthropic 的 API 格式，Codex 期望的是 OpenAI 的格式。如果你的本地模型只支持 OpenAI 格式，接 Claude Code 就需要一个转换层。openrig 本身不做协议转换，它只做配置注入，所以你需要确保本地服务支持目标工具期望的协议。

LM Studio 支持 OpenAI 兼容接口，所以接 Codex 比较直接。接 Claude Code 的话，需要看 LM Studio 是否支持 Anthropic 格式，或者用一个中间代理做转换。

7.4 配置调试的小技巧

调试配置时，我习惯用openrig apply --dry-run先看会生成什么，不实际写入。这样可以在不破坏现有配置的情况下检查配置是否正确。如果 openrig 不支持 dry-run，可以先把配置文件备份，apply 之后对比差异。

另一个技巧是用openrig show查看当前生效的配置，确认 openrig 解析出来的结果和你预期的一致。

7.5 性能与稳定性建议

openrig 本身很轻量，性能不是问题。稳定性方面，主要注意两点：一是 Node 版本要稳定，不要用太新的；二是配置文件要简洁，不要写太多不必要的配置，配置越复杂出问题的概率越高。

我自己的 openrig.yaml 一般控制在 50 行以内，只写必要的 provider 和 tool 配置，其他都用默认值。这样维护起来最省心。