企业官网建设流程全解析

1. 从零认识 openrig：它到底解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件支架项目，毕竟 rig 在英文里有“装配、支架”的意思。但结合 Claude Code、Codex、YAML、Node.js 这一串关键词，答案就清晰了：openrig 是一套围绕 AI 编程助手（Claude Code、Codex CLI 这类终端智能体）做配置编排与环境装配的工具思路。它的核心价值，是把散落在各处的模型接入配置、代理转发规则、CLI 启动参数、项目级 YAML 声明，收敛成一份可版本管理、可复用、可切换的“装配清单”。

我接触这类需求是从一个很具体的痛点开始的：手上同时跑 Claude Code 和 Codex CLI，一个走官方订阅，一个接第三方兼容端点，两边的配置文件格式不一样、环境变量命名不一样、切换模型时还要手动改一堆东西。每次换项目就得重新配一遍，配错了还得翻日志找原因。openrig 这类方案要解决的，就是这种“多智能体、多模型、多项目”场景下的配置地狱。

它适合谁？三类人最需要：一是同时使用多个 AI 编程 CLI 的开发者，二是需要在团队内统一 AI 工具配置的技术负责人，三是想把本地模型（比如通过 LM Studio 跑起来的模型）接进主流 CLI 的折腾党。哪怕你只是刚装完 Node.js、还在研究 Claude Code 怎么安装的新手，理解 openrig 的思路也能帮你少走很多弯路——因为它的本质不是某个神秘软件，而是一套约定优于配置的组织方法。

需要先说明一点：openrig 目前并不是一个官方统一发布的标准产品，更多是社区里对“开放式装配（open rigging）”这类实践的统称。所以下面讲的内容，是基于这类工具最常见的实现方式和我自己踩过的坑做的合理还原，具体到你手上的版本，细节可能有差异，但思路是通用的。

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

2.1 用 YAML 做声明式配置的底层逻辑

openrig 选择 YAML 作为配置载体，不是随便挑的。JSON 写起来太啰嗦，不允许注释，多行字符串处理起来很难受；TOML 表达嵌套结构时层级一深就变得别扭；而 YAML 在可读性和表达力之间取得了很好的平衡，尤其是它天然支持注释、锚点引用和多行文本，这几点在配置 AI 智能体时特别关键。

举个实际场景：你要给 Claude Code 配一个走第三方兼容端点的模型，同时给 Codex 配另一个端点，两者共享一部分请求头，但模型名和路径不同。用 YAML 的锚点可以这样写：

# openrig.yaml defaults: &common_headers Content-Type: application/json Accept: application/json providers: claude: endpoint: https://api.example.com/v1/messages headers: <<: *common_headers X-Client: claude-code model: claude-sonnet-4 codex: endpoint: https://api.example.com/v1/responses headers: <<: *common_headers X-Client: codex-cli model: gpt-5-codex

&common_headers定义锚点，<<: *common_headers做合并，改一处就能同步到所有引用点。这种能力在 JSON 里要靠工具预处理才能实现，YAML 原生就有。这就是为什么几乎所有现代 AI CLI 的配置文件——从 Claude Code 的 settings、Codex 的 config，到各种 CI 流水线——都优先选 YAML。

注意：YAML 对缩进极其敏感，Tab 和空格混用会直接报解析错误。我建议统一用两个空格缩进，并在编辑器里开启“显示空白字符”，一眼就能看出问题。

2.2 Node.js 作为运行时的必然性

Claude Code 和 Codex CLI 本身都是基于 Node.js 生态分发的，通过 npm 全局安装。openrig 作为它们的“装配层”，自然也要跑在同一个运行时上，这样才能直接调用 CLI、读写它们的配置目录、复用同一套环境变量体系。

Node.js 在这里扮演三个角色：第一是包管理与分发，通过 npm 或 npx 拉起 openrig 本体；第二是脚本执行，用 Node 脚本做配置生成、端点探测、健康检查；第三是跨平台适配，Windows、macOS、Linux 上同一份逻辑基本能跑通，这对需要“codex 安装 windows 桌面版”和“ubuntu 配置 claude code”两头兼顾的人特别友好。

版本选择上有个坑必须提前说。热搜里出现过error installing 24.21.0: node.js v24.21.0 is not yet released这类报错，本质是版本号写错了或者源里还没有这个版本。稳妥做法是装LTS 版本，去 Node.js 官网下载页选标着 LTS 的那个，别追最新的奇数版本。截至我写这篇的时候，Node 20 LTS 和 22 LTS 都是安全选择，Claude Code 和 Codex 对这两个版本兼容性最好。

# 检查当前版本 node -v npm -v # 如果版本太老，用 nvm 管理多版本（推荐） nvm install 22 nvm use 22

用 nvm 而不是直接覆盖安装，好处是可以在不同项目间切换 Node 版本，遇到某个 CLI 只兼容特定版本时不用反复卸载重装。

2.3 “装配”这个隐喻带来的设计约束

openrig 用“rig”这个词很讲究。装配意味着零件可替换、接口要统一、整体可拆卸。落到设计上就是三条约束：

• 配置与代码分离：模型名、端点、密钥全部外置到 YAML 和环境变量，不硬编码进脚本。
• 单一事实来源：同一份配置驱动 Claude Code、Codex 和本地模型接入，避免三处各写一遍。
• 可回滚：每次切换配置前先备份，出问题能一键还原。

这三条看着简单，但真正落地时，90% 的故障都出在违反其中某一条上。比如把密钥写死在脚本里，换环境时忘了改；或者三处配置各写各的，改了一处忘了另两处，结果 Claude Code 能跑、Codex 报cc switch local proxy failed while handling codex endpoint /responses这种端点不匹配的错。

3. 环境搭建实操：从装 Node.js 到跑通第一个配置

3.1 Node.js 安装的三种路径与选择建议

装 Node.js 有三条常见路径，各有适用场景：

我的建议很直接：只要你不是完全的新手，一律上 nvm。原因很简单，AI CLI 生态更新极快，今天 Claude Code 要 Node 18+，明天某个工具可能就要求 Node 20+，用 nvm 一条命令就能切，不用把系统环境搞得一团糟。

Windows 用户注意，nvm 在 Windows 上叫 nvm-windows，安装前要先卸载已有的 Node.js，否则会有路径冲突。装完后用管理员权限打开终端执行安装命令。

# macOS / Linux 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 或 ~/.zshrc # 安装并使用 LTS nvm install --lts nvm use --lts

3.2 Claude Code 与 Codex 的安装顺序

装完 Node.js，接下来装两个主角。顺序上我建议先装 Claude Code，再装 Codex，原因是 Claude Code 的安装脚本会顺带检查一些通用依赖，能帮你提前暴露环境问题。

# 安装 Claude Code npm install -g @anthropic-ai/claude-code # 验证 claude --version # 安装 Codex CLI npm install -g @openai/codex # 验证 codex --version

如果安装过程中卡在下载阶段，多半是 npm 源的问题，可以临时切到国内镜像：

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

装完后如果claude --version报“command not found”，八成是 npm 全局 bin 目录没进 PATH。用npm config get prefix看下全局目录，把它加到 PATH 里就行。

3.3 openrig 配置目录的初始化

openrig 的配置通常放在项目根目录或用户主目录下的隐藏文件夹里。我习惯在项目根目录建一个.openrig/目录，里面放主配置和各个 provider 的片段：

mkdir -p .openrig/providers touch .openrig/openrig.yaml

目录结构建议这样组织：

.openrig/ ├── openrig.yaml # 主配置，声明启用哪些 provider ├── providers/ │ ├── claude.yaml # Claude Code 相关配置 │ ├── codex.yaml # Codex 相关配置 │ └── local.yaml # 本地模型（如 LM Studio）配置 └── .env.local # 密钥等敏感信息，加入 .gitignore

把敏感信息单独放.env.local并加进.gitignore，是防止密钥泄露的基本操作。我见过太多人把 API key 直接写进 YAML 然后推到公开仓库，后果不用多说。

4. 配置细节拆解：让 Claude Code 和 Codex 各就各位

4.1 Claude Code 的配置要点与常见报错

Claude Code 的配置核心是模型端点和认证方式。如果你用的是官方订阅，登录后基本开箱即用；如果要接第三方兼容端点或本地模型，就得手动指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这类环境变量。

# 接入本地 LM Studio 的示例 export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="lm-studio"

热搜里有个高频报错：your organization has disabled claude subscription access for claude code。这个提示的意思是当前账号的组织策略不允许用订阅额度跑 Claude Code。遇到这种情况，要么找管理员开通权限，要么改用 API key 计费方式，要么接第三方兼容端点。这不是配置写错了，是账号层面的策略限制，改配置文件没用。

另一个常见问题是 VS Code 里配置 Claude Code。如果你用claude code for vs code这个扩展，注意扩展本身只是入口，真正的 CLI 还是要全局装好。扩展报错时，先在终端里跑claude确认 CLI 本身正常，再排查扩展设置。

4.2 Codex 的配置与端点匹配陷阱

Codex 的配置坑更多一些，尤其是端点路径。热搜里那个cc switch local proxy failed while handling codex endpoint /responses就是典型：Codex 期望的端点是/responses，但你配的代理或中转服务可能只支持/chat/completions，路径对不上就报错。

Codex 的配置一般放在~/.codex/config.yaml或项目级配置里：

# ~/.codex/config.yaml model: gpt-5-codex provider: name: custom base_url: https://api.example.com/v1 env_key: CODEX_API_KEY

关键点在于base_url后面到底要不要带/v1、端点路径是/responses还是/chat/completions，这取决于你的服务商。我的经验是：先看服务商文档给的完整 URL 示例，把 base 和 path 拆开对应填，别凭感觉拼。

还有个报错the 'gpt-5.6-sol' model is not supported when using codex with a...，意思是模型名不被当前接入方式支持。Codex 对模型名有白名单校验，写了个不存在的模型名就会拦下来。解决办法是查你所用服务商实际支持的模型列表，填对名字。

4.3 用 YAML 统一管理多 provider

把 Claude 和 Codex 的配置统一到 openrig 主文件里，是这套方案的精髓。主配置只做声明和引用，具体细节放各自的片段文件：

# .openrig/openrig.yaml version: 1 active: claude # 当前激活的 provider providers: claude: config: ./providers/claude.yaml env_file: ./.env.local codex: config: ./providers/codex.yaml env_file: ./.env.local local: config: ./providers/local.yaml

切换 provider 时只改active一行，其余不动。这样既保证了单一事实来源，又让切换成本降到最低。配合一个简单的 Node 脚本，还能实现“切换即生效”：

// scripts/switch.js const fs = require('fs'); const yaml = require('js-yaml'); const cfg = yaml.load(fs.readFileSync('.openrig/openrig.yaml', 'utf8')); const target = process.argv[2]; if (!cfg.providers[target]) { console.error(`未知 provider: ${target}`); process.exit(1); } cfg.active = target; fs.writeFileSync('.openrig/openrig.yaml', yaml.dump(cfg)); console.log(`已切换到 ${target}`);

运行node scripts/switch.js codex就能切换。这种小脚本看着不起眼，但当你一天要在多个模型间来回切十几次时，省下的时间很可观。

5. 常见故障排查与避坑经验实录

5.1 安装类问题速查

安装类问题有个通用排查顺序：先确认 Node 版本，再确认 npm 源，最后确认 PATH。这三步能解决八成安装问题。

5.2 运行类问题与排查思路

运行时的报错更隐蔽，我整理了几个高频场景：

端点不匹配：表现为failed while handling codex endpoint /responses。排查方法是直接用 curl 测端点通不通：

curl -X POST https://api.example.com/v1/responses \ -H "Authorization: Bearer $CODEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-5-codex","input":"hello"}'

curl 能通说明配置对，CLI 报错就是参数传递问题；curl 也不通就是端点或密钥问题。

模型不支持：报错里会明确写出模型名。去服务商文档核对支持的模型列表，别用猜的。

组织策略限制：像organization has disabled claude subscription access这种，属于账号层面，配置改不动，只能走 API 计费或换接入方式。

代理转发失败：cc switch local proxy failed这类，重点检查代理服务的路由规则，确认它认识/responses这个路径。

5.3 我踩过的三个真实坑

第一个坑是配置文件编码。有次在 Windows 上用记事本编辑 YAML，保存成了带 BOM 的 UTF-8，结果解析器一直报奇怪的语法错误。后来统一用 VS Code 编辑，并在设置里关掉 BOM，问题消失。这个坑很隐蔽，因为文件内容看着完全正常。

第二个坑是环境变量优先级。我同时在 shell 配置、.env文件和 openrig 配置里设了ANTHROPIC_API_KEY，结果三者不一致，CLI 用了哪个完全靠猜。后来定下规矩：密钥只在.env.local里设一处，其他地方的都删掉。单一事实来源这条原则，在密钥管理上尤其重要。

第三个坑是版本漂移。某次 Claude Code 自动更新后，之前能用的配置突然报错，查了半天发现是新版本改了某个参数的默认值。教训是：生产环境里锁定 CLI 版本，别开自动更新，升级前先在测试环境验证。

提示：每次改动配置前，先cp openrig.yaml openrig.yaml.bak备份一份。出问题时对比备份，能快速定位是哪次改动引入的。

6. 进阶玩法：本地模型接入与多环境协同

6.1 把 LM Studio 的本地模型接进 Claude Code

本地模型接入是很多人折腾 openrig 的初衷。LM Studio 启动后会暴露一个兼容 OpenAI 格式的本地端点，默认在http://localhost:1234/v1。把它接进 Claude Code 的关键，是让 Claude Code 以为自己在跟一个兼容端点说话：

# .openrig/providers/local.yaml endpoint: http://localhost:1234/v1 model: local-model-name api_key: lm-studio

然后在环境变量里指向这个端点。实测下来，本地模型在简单代码补全和问答上够用，但复杂推理和长上下文还是得靠云端模型。我的用法是：日常小改动走本地，省额度；复杂重构走云端，保质量。

6.2 多环境配置的隔离策略

团队协作时，开发、测试、生产三套环境的配置必须隔离。openrig 的做法是按环境拆文件：

.openrig/ ├── openrig.yaml # 主配置，引用环境 ├── env/ │ ├── dev.yaml │ ├── staging.yaml │ └── prod.yaml

主配置里用变量引用当前环境，启动时通过环境变量OPENRIG_ENV决定加载哪套。这样同一份代码在不同环境跑，配置自动切换，不会出现“测试环境误连生产端点”这种事故。

6.3 与 VS Code 的协同配置

VS Code 里同时用 Claude Code 扩展和 Codex 时，注意工作区设置和用户设置的优先级。工作区设置会覆盖用户设置，所以项目级的 openrig 配置应该放在工作区的.vscode/settings.json里引用，而不是全局。这样换项目时配置自动跟着走，不用手动切。

{ "claude-code.configPath": "${workspaceFolder}/.openrig/openrig.yaml", "codex.configPath": "${workspaceFolder}/.openrig/providers/codex.yaml" }

用${workspaceFolder}变量而不是绝对路径，是保证配置可移植的关键。团队里每个人的项目路径不一样，写死绝对路径别人就用不了。

7. 关于 openrig 这套思路的个人体会

折腾了这么久，我最大的感受是：openrig 的价值不在于它是不是一个“标准工具”，而在于它代表的那套把配置当代码管理的思路。YAML 做声明、Node.js 做执行、环境变量做隔离、Git 做版本控制，这四样东西组合起来，就能把原本混乱的 AI 工具配置变得井井有条。

如果你刚开始接触，我的建议是从最小可用配置起步：先装好 Node.js LTS，装好 Claude Code，跑通官方登录，再慢慢加 Codex 和本地模型。别一上来就追求大而全的配置，那样只会被各种报错劝退。每加一个 provider，就用 curl 验证一次端点，确认通了再往下走。

最后分享一个我一直在用的小技巧：在 openrig 配置里加一个healthcheck字段，记录每个 provider 的验证命令。切换配置后先跑一遍健康检查，全绿了再开始干活。这个习惯帮我省下了无数次“配了半天发现端点根本不通”的无效折腾。配置这东西，稳比快重要，一次配对比反复调试划算得多。