企业官网建设流程全解析

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，很多人会以为是某个硬件外设或者开源机械臂项目。实际上，结合它周围高频出现的 Claude Code、Codex、YAML、Node.js 这些词，可以判断出它属于 AI 编程助手工具链里的一个配置编排层。简单说，openrig 做的事情就是：把 Claude Code、Codex 这类命令行 AI 编程工具，以及它们背后要调用的模型服务、代理端点、环境变量，用一份结构化的 YAML 文件统一管理起来，让开发者不用每次手动去改一堆散落在各处的配置。

它解决的核心痛点很具体。现在用 Claude Code 或者 Codex 的人越来越多，但这两个工具各自的配置方式不一样，Claude Code 依赖环境变量和 settings 文件，Codex 走的是自己的 config 体系，如果你还想在两者之间切换不同的模型后端，比如今天用官方端点、明天换成 DeepSeek 或者本地 LM Studio，手动改配置很容易出错。openrig 的思路就是把这些东西抽象成一份声明式的 YAML，你只描述"我要用哪个工具、连哪个端点、走哪个模型"，剩下的环境变量注入、路径拼接、启动参数组装，全部由它来处理。

适合谁来参考这份内容？三类人最需要。第一类是刚接触 Claude Code 或 Codex，被安装和配置卡住的开发者，尤其是 Windows 环境下遇到各种路径和权限问题的；第二类是已经在用这些工具，但每次切换模型或端点都要翻文档、改配置，效率很低的中级用户；第三类是想把 AI 编程工具集成进团队工作流，需要一套可复制、可版本管理的配置方案的技术负责人。不管你属于哪一类，下面这些内容都是从实际踩坑里总结出来的，不是照搬官方文档。

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

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

openrig 选择 YAML 作为配置载体，这个决定背后有很实际的考量。JSON 的问题是写不了注释，而 AI 工具链的配置里，注释极其重要——你需要标注"这个端点对应哪个模型""这个 key 从哪申请""什么情况下要改这个值"。TOML 虽然支持注释，但嵌套结构表达起来比较啰嗦，尤其是当你要描述多个工具、多个端点、多层级的模型映射时，TOML 的表格语法会变得很难读。

YAML 的优势在于它天然适合表达层级关系，而且支持锚点和引用，这一点在 openrig 场景下特别有用。比如你定义了三个端点，其中两个共享同一套请求头配置，用 YAML 的锚点可以只写一次，其他地方引用就行。另外 YAML 对多行字符串的支持也比 JSON 友好，写系统提示词或者自定义指令的时候不用到处转义。

注意：YAML 对缩进极其敏感，Tab 和空格混用是最常见的报错来源。建议在编辑器里把 Tab 自动转成 2 个空格，VSCode 里搜 "insert spaces" 就能设置。

2.2 为什么依赖 Node.js 生态

Claude Code 和 Codex 的 CLI 版本都是基于 Node.js 分发的，这是 openrig 必须依赖 Node.js 的根本原因。Node.js 在这里扮演的是运行时角色，它提供了 npm 包管理能力，让 Claude Code 和 Codex 可以通过全局安装的方式在终端里直接调用。同时 Node.js 的版本管理也很关键，因为不同版本的 Claude Code 对 Node.js 版本有不同要求，装错了版本会出现各种奇怪的报错。

实际使用中，Node.js 的 LTS 版本是最稳妥的选择。截至目前的经验，Node.js 20.x 和 22.x 这两个 LTS 版本对 Claude Code 和 Codex 的兼容性最好。如果你用的是 Windows，建议通过官方安装包安装，不要用某些第三方包管理器，因为路径注册方式不一样，后面配置环境变量的时候容易出问题。

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

openrig 的设计里有一个很重要的分层思想，理解了这个，你就能明白为什么有些配置改了不生效。它把配置分成三层：

• 全局层：存在用户主目录下，对所有项目生效，通常放 API key、默认端点、通用偏好设置
• 项目层：存在项目根目录，只对当前项目生效，放项目特定的模型选择、自定义指令、忽略规则
• 会话层：通过环境变量或命令行参数临时注入，优先级最高，适合临时切换模型做对比测试

这个分层的意义在于，你可以把敏感的 API key 放在全局层，把项目相关的配置放在项目层并提交到版本控制，团队成员拉下来就能用，而不用每个人都去问 key 是什么。会话层则给了你最大的灵活性，比如你想临时用 DeepSeek 跑一个任务，不用改任何文件，直接在启动命令前加环境变量就行。

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

3.1 Node.js 环境准备的正确姿势

安装 Node.js 看起来简单，但这里踩坑的人最多。Windows 用户去官网下载 LTS 安装包，一路下一步就行，但有两个地方要注意。第一，安装路径不要有中文和空格，默认的C:\Program Files\nodejs\其实就带空格，虽然大部分情况没问题，但某些 npm 包在处理路径时会出幺蛾子，建议改成C:\nodejs\这种干净路径。第二，安装完成后一定要验证，打开新的终端窗口，执行：

node -v npm -v

两个命令都能输出版本号才算成功。如果提示"不是内部或外部命令"，说明环境变量没配好，手动把 Node.js 安装目录加到系统 PATH 里。

Ubuntu 用户建议用 NodeSource 的源来装，比系统自带的版本新很多：

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

装完之后同样用node -v验证。这里有个经验：如果你之前用 apt 装过旧版本，先sudo apt remove nodejs卸干净再装，不然会出现两个版本打架的情况。

提示：网上有些教程会让你装 nvm 来管理 Node.js 版本，这在需要频繁切换版本的场景下确实有用，但对 openrig 来说不是必须的。如果你只用一个版本，直接装 LTS 更省事。

3.2 Claude Code 与 Codex 的安装差异

这两个工具的安装方式有区别，不能混为一谈。Claude Code 的 CLI 版本通过 npm 全局安装：

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

安装完成后，在终端输入claude就能启动。第一次启动会引导你登录或者配置 API key。这里有个常见问题：如果你的组织禁用了 Claude 订阅访问，会看到 "your organization has disabled claude subscription access for claude code" 这样的提示，这时候你需要改用 API key 方式，而不是订阅登录方式。

Codex 的安装稍微复杂一点，它有不同的分发渠道。通过 npm 安装的方式是：

npm install -g @openai/codex

但 Codex 对 Node.js 版本的要求更严格，如果你看到 "error installing 24.21.0: node.js v24.21.0 is not yet released" 这类报错，说明你的 npm 在尝试安装一个不存在的 Node.js 版本，这通常是 npm 缓存或者源的问题，执行npm cache clean --force后重试。

3.3 YAML 配置文件的结构设计

openrig 的 YAML 配置文件通常长这样，我以一个实际用过的结构为例：

version: 1 defaults: tool: claude-code endpoint: official endpoints: official: base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY deepseek: base_url: https://api.deepseek.com api_key_env: DEEPSEEK_API_KEY model_map: claude-sonnet: deepseek-chat local: base_url: http://localhost:1234/v1 api_key_env: LMSTUDIO_KEY tools: claude-code: env: ANTHROPIC_BASE_URL: "{{endpoint.base_url}}" ANTHROPIC_API_KEY: "{{env(endpoint.api_key_env)}}" codex: config_path: ~/.codex/config.yaml env: OPENAI_BASE_URL: "{{endpoint.base_url}}"

这个结构的关键在于endpoints和tools的分离。端点描述的是"连到哪里"，工具描述的是"怎么连"。这样设计的好处是，当你新增一个模型服务时，只需要在 endpoints 里加一段，所有工具都能复用。model_map则解决了不同服务商模型命名不一致的问题，比如 Claude 叫 claude-sonnet，DeepSeek 叫 deepseek-chat，通过映射表自动转换。

3.4 环境变量注入的时机问题

这是最容易出错的地方。openrig 在启动工具之前会把 YAML 里定义的环境变量注入到子进程里，但如果你是在已经打开的终端里手动 export 了变量，两者会冲突。优先级是这样的：会话层（手动 export）> 项目层 > 全局层。也就是说，如果你手动 export 了一个值，YAML 里的配置就不会生效。

实际排查的时候，先用env | grep ANTHROPIC看看当前终端里有没有残留的环境变量。如果有，要么 unset 掉，要么就接受它覆盖 YAML 配置的事实。我个人的习惯是，所有持久化配置都放 YAML，临时测试才用 export，测试完立刻关掉终端窗口，避免污染后续会话。

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

4.1 从零搭建 openrig 工作流的完整步骤

假设你是一台全新的 Windows 机器，下面是我实际走过一遍的流程。

第一步，装 Node.js。去官网下载 22.x LTS 的 Windows 安装包，安装路径改成C:\nodejs，安装时勾选"自动添加到 PATH"。装完打开新的 PowerShell，node -v应该输出v22.x.x。

第二步，装 Claude Code 和 Codex。这里建议先配置 npm 的国内镜像源，不然下载速度会很慢：

npm config set registry https://registry.npmmirror.com npm install -g @anthropic-ai/claude-code npm install -g @openai/codex

第三步，创建 openrig 的配置目录。在用户主目录下建一个.openrig文件夹，里面放config.yaml。Windows 下就是C:\Users\你的用户名\.openrig\config.yaml。

第四步，填入端点信息。如果你用官方服务，endpoints 里配官方地址和对应的 key 环境变量名；如果用第三方兼容端点，把 base_url 换成对应的地址。这里要注意，有些第三方端点虽然兼容 OpenAI 格式，但路径不一样，有的要加/v1，有的不要，这个必须看服务商的文档确认。

第五步，验证配置。openrig 一般会提供一个openrig check或者类似的命令来校验 YAML 语法和端点连通性。如果没有这个命令，就手动启动一次 Claude Code，看能不能正常对话。启动命令通常是openrig run claude-code这种形式。

4.2 接入本地模型服务的参数计算

很多人想用 LM Studio 或者类似工具跑本地模型，然后让 Claude Code 调用。这里有几个参数必须算清楚。

首先是上下文长度。本地模型的上下文窗口通常比云端小，比如你跑一个 7B 的模型，上下文可能只有 8K 或者 32K。而 Claude Code 默认会发送比较长的系统提示和文件内容，如果超出本地模型的上下文限制，请求会直接失败。解决办法是在 YAML 里给这个端点单独设置max_tokens和context_limit，让 openrig 在发送前做截断。

其次是并发数。本地模型的推理速度受限于你的显卡，如果同时发多个请求，每个都会变慢。在 YAML 里可以设置concurrency: 1，强制串行处理。这个值官方端点可以设高一些，本地端点建议就设 1。

最后是超时时间。本地模型首次加载需要时间，如果超时设得太短，第一个请求会失败。建议本地端点的timeout设到 120 秒以上，官方端点 30 秒就够了。

4.3 在 VSCode 里集成 Claude Code

VSCode 有 Claude Code 的官方扩展，装完之后可以在编辑器里直接调用。但扩展和 CLI 的配置是分开的，扩展读的是 VSCode 的设置，不是 openrig 的 YAML。如果你想让两者用同一套端点配置，需要手动把 YAML 里的值同步到 VSCode 的 settings.json 里。

具体做法是，在 VSCode 的 settings.json 里加：

{ "claude-code.environmentVariables": { "ANTHROPIC_BASE_URL": "你的端点地址", "ANTHROPIC_API_KEY": "你的key" } }

这样扩展启动的时候就会用这些环境变量。缺点是每次改 YAML 都要手动同步一次，比较麻烦。如果你频繁切换端点，建议还是以 CLI 为主，VSCode 扩展只在固定端点下使用。

4.4 Codex 接入第三方模型的配置方法

Codex 默认连的是 OpenAI 的端点，但通过改配置可以接入 DeepSeek 或者其他兼容 OpenAI 格式的服务。Codex 的配置文件通常在~/.codex/config.yaml，内容大概是这样：

model: deepseek-chat provider: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY}

这里的关键是base_url要带/v1，因为 Codex 内部拼接路径的时候是按 OpenAI 的规范来的。如果你接的服务商不需要/v1，就要在 base_url 里去掉，或者在 openrig 层面做路径重写。

还有一个坑是模型名称。Codex 会校验模型名是否在支持列表里，如果你填了一个它不认识的模型名，会报 "the 'gpt-5.6-sol' model is not supported" 这类错误。解决办法是在配置里加上model_map，把 Codex 认识的模型名映射到你实际要用的模型。

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

5.1 安装阶段的典型报错

5.2 运行阶段的连接问题

连接问题分两种，一种是完全连不上，一种是连上了但返回错误。完全连不上通常是 base_url 写错了，或者本地服务没启动。排查方法是先用 curl 直接测端点：

curl -X POST https://你的端点/v1/chat/completions \ -H "Authorization: Bearer 你的key" \ -H "Content-Type: application/json" \ -d '{"model":"模型名","messages":[{"role":"user","content":"test"}]}'

如果 curl 能通但 Claude Code 不通，那就是 openrig 的环境变量注入有问题，检查 YAML 里的变量名和工具实际读取的变量名是否一致。Claude Code 读的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，Codex 读的是OPENAI_BASE_URL和OPENAI_API_KEY，名字对不上就不会生效。

连上了但返回错误，常见的是 401 和 404。401 是 key 无效或者没传对，404 是路径不对。有些第三方端点要求 base_url 结尾不带斜杠，有些要求带，这个只能试。我的经验是，先在 curl 里把路径试通，再往 YAML 里填。

5.3 模型切换后行为异常的排查

切换模型后如果发现回答质量突然下降，或者工具调用不工作，先确认模型是否支持 function calling。Claude Code 和 Codex 都依赖 function calling 来执行终端命令和读写文件，如果切换到的模型不支持这个能力，工具就会退化成纯聊天模式。

排查方法是看日志。Claude Code 启动时加--verbose参数可以看到详细的请求和响应。如果响应里没有 tool_calls 字段，说明模型没返回工具调用，要么是模型不支持，要么是提示词没适配。这种情况下，要么换回支持 function calling 的模型，要么在 YAML 里给这个端点单独配置一套简化版的提示词。

5.4 配置文件版本管理的经验

openrig 的 YAML 文件建议提交到项目的版本控制里，但 API key 绝对不能提交。做法是在 YAML 里只写环境变量名，不写实际值，然后在项目根目录放一个.env.example说明需要哪些变量。团队成员拉下来之后，自己创建.env填入真实的 key，.env加到.gitignore里。

这样做的另一个好处是，当端点配置需要调整时，改 YAML 提交，所有人都能同步到，不用在群里发配置截图。我见过太多团队因为配置不同步导致"我这里能跑你那里跑不了"的问题，用版本管理配置之后这类问题基本消失了。

5.5 性能调优的几个实用参数

如果你觉得 Claude Code 响应慢，可以调这几个参数。max_tokens控制单次响应的最大长度，设小一点能加快返回速度，但可能截断长回答。temperature设低一些（比如 0.2）能让输出更稳定，适合代码生成场景。timeout根据端点位置调整，本地端点设长，云端端点设短。

还有一个容易被忽略的是retry次数。网络不稳定的时候，适当的重试能避免请求失败，但重试太多会拖慢整体速度。建议设 2 次，超过 2 次还失败说明是端点本身的问题，重试也没用。

6. 我个人的一些实操体会

用 openrig 这套东西有一段时间了，最大的感受是配置的集中管理确实省心，但前提是你得把 YAML 的结构设计好。我一开始把所有东西都塞在一个文件里，后来端点多了之后变得很难维护，改成按端点拆分成多个文件，主配置里用include引用，清晰了很多。

另一个体会是，不要过度追求自动化。有些配置项其实很少变，手动改一下也就几秒钟的事，硬要抽象成变量反而增加了理解成本。openrig 的价值在于管理那些频繁切换的配置，比如端点和模型，而不是把所有东西都抽象一遍。

最后分享一个小技巧：在 YAML 里给每个端点加一个description字段，写清楚这个端点是干什么的、什么时候用。过几个月再回来看的时候，你会感谢自己当初写了注释。