企业官网建设流程全解析

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，我下意识以为是某个硬件外设的开源项目，毕竟“rig”这个词在矿机、直播设备、测试台架这些圈子里太常见了。但把 openrig 和 claude code、codex、yaml、node.js 这几个词摆在一起看，方向就清楚了——这是一个围绕 AI 编程助手做配置编排、环境搭建和本地代理转发的工具型项目。说白了，它解决的是“我手头有好几个 AI 编程工具，怎么让它们统一跑起来、统一配置、统一切换”的问题。

我接触 AI 编程助手这条线有一段时间了，从最早的命令行补全工具，到后来的 claude code、codex 这类能直接读写项目文件、执行终端命令的 agent 型工具，踩过的坑不算少。最典型的一个痛点就是：每个工具的配置格式不一样，认证方式不一样，模型接入方式也不一样。claude code 有自己的一套配置逻辑，codex 又是另一套，你想让它们都指向同一个本地模型或者同一个第三方接口，得分别折腾。openrig 的价值就在这里——它试图用一份 yaml 配置，把多个 AI 编程工具的运行环境、模型端点、代理规则统一管起来。

那它适合谁用？我觉得有三类人最需要关注。第一类是同时用 claude code 和 codex 的开发者，尤其是需要在不同模型之间来回切换的；第二类是想把 AI 编程助手接到本地模型（比如通过 LM Studio 跑起来的模型）上的人，因为本地模型的接口格式和官方接口往往有差异，中间需要一层转换；第三类是在团队里负责统一开发环境的人，一份 yaml 分发下去，大家的工具配置就一致了，省得每个人各自为战。

openrig 这个名字里的“rig”我理解成“装配、搭台子”的意思，就是把散落的工具和配置装配成一个能稳定运转的整体。它本身不是模型，也不是编程助手，而是一层编排和代理的中间件。这个定位很关键，理解了这一点，后面所有的配置逻辑就都顺了。

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

2.1 为什么用 yaml 做统一配置层

openrig 选择 yaml 作为配置载体，这个决定我认为是非常务实的。你去看 claude code 和 codex 各自的配置，有的是 json，有的是 toml，有的干脆靠环境变量。格式不统一带来的直接后果就是：你没法用一套逻辑去管理它们。yaml 的好处在于结构清晰、支持注释、嵌套表达能力强，而且 node.js 生态里解析 yaml 的库非常成熟，js-yaml 几乎是标配。

更重要的是，yaml 对人类友好。你写一个多工具的配置，里面要区分全局设置、每个工具的独立设置、模型端点、代理规则，用 json 写会满屏引号和括号，改起来容易出错。yaml 的缩进式结构让层级关系一目了然，团队协作时 review 配置也轻松很多。我实测下来，一份结构良好的 openrig yaml，新人看十分钟就能明白每个字段是干什么的。

这里有个细节值得说：yaml 对缩进极其敏感，tab 和空格混用会直接报错。我见过太多人从网页复制配置片段，结果粘贴进去全是 tab，解析直接失败。所以 openrig 的配置最好用统一的编辑器，设置成“tab 转 2 空格”，能省掉大量莫名其妙的报错。

2.2 node.js 作为运行时底座的原因

openrig 跑在 node.js 上，这个选型背后有明确的逻辑。claude code 和 codex 这类工具，很多本身就是 node.js 写的或者提供 npm 安装方式，运行时环境天然重合。用 node.js 做底座，意味着你不需要额外装 python、go 或者 rust 的运行时，一个 node 环境就能把整套工具链撑起来。

node.js 的另一个优势是它的异步 IO 模型特别适合做代理转发。openrig 要处理的核心场景之一就是请求转发——把 claude code 或 codex 发出的请求，转发到本地模型或者第三方接口。这种场景下，请求的并发处理、流式响应的透传，node.js 的 event loop 机制处理起来很顺手。而且 npm 生态里有大量现成的 http 代理、流处理库，不用从零造轮子。

不过 node.js 的版本管理是个坑。我强烈建议用 nvm 或者 fnm 来管理 node 版本，不要直接装系统级的 node。因为不同工具对 node 版本的要求可能不一样，有的要 18 LTS，有的要 20 LTS，混在一起容易出问题。openrig 本身对 node 版本的要求，我建议至少 18 LTS 起步，20 LTS 更稳。

2.3 代理层设计的核心考量

openrig 最核心的技术点，我认为是它的代理层设计。为什么需要代理？因为 claude code 和 codex 默认都指向官方的接口端点，但实际使用中，很多人需要把它们指向别的模型服务——可能是本地跑的模型，可能是团队内部的网关，也可能是第三方兼容接口。这些服务的接口格式和官方接口往往有差异，直接改工具的配置又很麻烦，所以中间加一层代理做格式转换和路由是最干净的方案。

代理层要解决三个问题：第一是端点重写，把工具发出的请求地址改到目标服务；第二是格式适配，不同模型的请求体和响应体结构不一样，需要转换；第三是认证透传，把工具带的认证信息正确传递给下游服务。openrig 通过 yaml 配置来定义这些规则，你只需要声明“claude code 的请求走哪个端点、用什么格式、带什么认证”，剩下的交给它处理。

我踩过的一个坑是：代理层如果对流式响应处理不当，会导致 claude code 那边一直卡着不输出。流式响应的每个 chunk 都要及时透传，不能等整个响应结束再一次性返回。openrig 在这块如果用的是 node.js 的 stream pipe，基本不会有问题，但如果自己手写缓冲逻辑，就要特别注意 flush 时机。

3. 环境搭建与核心配置实操

3.1 node.js 环境准备与版本选择

先把地基打好。node.js 的安装我推荐两种方式，看你习惯。如果你只是临时用，去 node.js 官网下载 LTS 版本的安装包，一路下一步就行。但如果你要长期折腾 AI 编程工具这条线，强烈建议用版本管理器。

在 macOS 或 Linux 上，用 nvm 是最省心的：

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

装完之后重开终端，然后：

nvm install 20 nvm use 20 nvm alias default 20

Windows 用户可以用 nvm-windows，或者干脆用 fnm，速度更快。装好之后验证一下：

node -v npm -v

这里有个常见报错要提前说：如果你看到类似“error installing 24.21.0: node.js v24.21.0 is not yet released”这种提示，说明你指定的版本号根本不存在，或者 nvm 的远程版本列表没更新。解决办法是先nvm ls-remote看看有哪些可用版本，别凭记忆瞎写版本号。另外，奇数版本号（如 21、23）是开发版，生产环境建议用偶数 LTS 版本。

3.2 openrig 的安装与初始化

node 环境就绪后，openrig 的安装通常走 npm 全局安装的路子：

npm install -g openrig

如果 npm 下载慢，可以临时切到国内镜像源：

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

装完之后跑一下openrig --version确认安装成功。接下来是初始化配置文件。openrig 一般会在用户目录下找配置文件，常见位置是~/.openrig/config.yaml或者当前项目根目录的openrig.yaml。我建议先用全局配置做基础设置，项目级的配置做覆盖，这样不同项目可以用不同的模型端点。

初始化的时候，openrig 可能会生成一份模板配置。如果没有自动生成，手动创建一个：

version: 1 tools: claude-code: enabled: true endpoint: http://localhost:1234/v1 codex: enabled: true endpoint: http://localhost:1234/v1 proxy: port: 8787 logLevel: info

这份配置的意思是：启用 claude code 和 codex 两个工具，它们的请求都转发到本地的 1234 端口（假设你本地用 LM Studio 跑模型，默认端口就是 1234），代理服务本身监听 8787 端口。

3.3 yaml 配置文件的字段详解

配置文件的每个字段都有讲究，我逐个拆开讲。

version字段是配置格式的版本号，openrig 升级后如果配置格式有变化，靠这个字段做兼容。别删，也别乱改。

tools下面是每个工具的独立配置。enabled控制是否启用，调试的时候可以单独关掉某个工具。endpoint是这个工具请求要发往的地址。这里要注意，endpoint 的路径部分很关键，有的服务是/v1，有的是/v1/chat/completions，写错了会直接 404。

proxy段是代理服务本身的设置。port是监听端口，别和系统里其他服务冲突，8787 是个比较安全的选择。logLevel控制日志详细程度，调试阶段设成debug，稳定后改回info，不然日志刷屏。

如果要接入需要认证的服务，配置里要加认证信息：

tools: claude-code: enabled: true endpoint: https://api.example.com/v1 auth: type: bearer token: ${CLAUDE_API_KEY}

注意${CLAUDE_API_KEY}这种写法是从环境变量读取，不要把密钥明文写在 yaml 里。这是安全底线，配置文件很可能被提交到 git，明文密钥泄露就是事故。

3.4 接入本地模型的完整流程

把 claude code 接到本地模型上，是 openrig 最实用的场景之一。完整流程是这样的。

第一步，本地先把模型服务跑起来。以 LM Studio 为例，加载一个模型，启动本地 server，默认监听 1234 端口，接口格式是 OpenAI 兼容的。启动后你可以用 curl 验证一下：

curl http://localhost:1234/v1/models

能返回模型列表就说明服务正常。

第二步，配置 openrig 把 claude code 的请求转发到这个端点。因为 claude code 默认的请求格式和 OpenAI 格式不完全一样，openrig 需要做一层转换。配置里通常要指定转换规则：

tools: claude-code: enabled: true endpoint: http://localhost:1234/v1 adapter: openai-compatible model: local-model-name

adapter字段告诉 openrig 用哪种格式转换器，model指定实际调用的模型名。这个模型名要和本地服务里加载的模型标识一致，写错了会报“model not found”。

第三步，启动 openrig 代理：

openrig start

第四步，把 claude code 的请求地址指向 openrig 的代理端口。这一步通常通过环境变量或者 claude code 自己的配置完成。具体方式取决于 claude code 的版本，有的支持ANTHROPIC_BASE_URL这类环境变量，有的要在配置文件里改。

我实测下来，这套流程跑通后，claude code 就能用本地模型做代码补全和对话了。但要注意，本地模型的能力和官方模型差距可能很大，尤其是长上下文和工具调用能力，别期望值太高。

4. 多工具协同与代理转发实战

4.1 claude code 与 codex 的配置差异处理

claude code 和 codex 虽然都是 AI 编程助手，但它们的配置逻辑和请求格式差异不小。claude code 的请求体里，消息结构、工具调用格式、系统提示词的组织方式，和 codex 都不一样。openrig 要同时管这两个，就得在代理层做区分。

我的做法是在配置里给每个工具单独指定 adapter：

tools: claude-code: enabled: true endpoint: http://localhost:1234/v1 adapter: anthropic-to-openai codex: enabled: true endpoint: http://localhost:1234/v1 adapter: openai-native

anthropic-to-openai表示把 anthropic 风格的请求转成 OpenAI 风格，openai-native表示 codex 本身就是 OpenAI 风格，不用转换。这样两个工具可以共用同一个本地模型端点，但各自走各自的转换逻辑。

这里有个细节：claude code 的工具调用（tool use）格式和 OpenAI 的 function calling 格式差异很大。如果本地模型不支持工具调用，或者转换层处理不好，claude code 执行终端命令、读写文件这些功能就会失效。我建议先用简单的对话测试，确认基础通路没问题，再逐步测试工具调用。

4.2 代理转发中的流式响应处理

流式响应是代理转发里最容易出问题的地方。claude code 和 codex 都期望服务端以 SSE（Server-Sent Events）的形式流式返回内容，这样用户能看到逐字输出的效果。如果代理层把流式响应缓冲成完整响应再返回，用户体验会变得极差，而且可能触发超时。

openrig 在 node.js 里处理流式响应，核心是用 stream 的 pipe 机制。请求进来后，代理层把请求转发给下游服务，下游返回的响应流直接 pipe 回客户端，中间只做必要的格式转换，不做缓冲。这样每个 chunk 都能及时透传。

如果你自己写代理逻辑，要特别注意这几点：不要用await response.text()这种一次性读取的方式；要用response.body的流式接口；转换格式时如果必须缓冲，要设置合理的 flush 阈值，不能等整个响应结束。

我踩过的一个坑是：某些本地模型服务的流式响应格式不规范，chunk 之间没有正确的分隔符，导致代理层解析出错。解决办法是在代理层加一层容错，遇到解析不了的 chunk 就原样透传，别直接报错中断。

4.3 多模型切换的配置策略

实际使用中，你可能需要在不同模型之间切换——写代码用一个模型，写文档用另一个，调试用本地小模型。openrig 的配置支持定义多个模型端点，然后通过切换配置或者命令行参数来选择。

一种做法是在 yaml 里定义模型组：

models: coding: endpoint: http://localhost:1234/v1 model: deepseek-coder general: endpoint: http://localhost:1234/v1 model: qwen fast: endpoint: http://localhost:8080/v1 model: small-model

然后在工具配置里引用：

tools: claude-code: enabled: true modelRef: coding

这样切换模型只需要改modelRef的值，不用改一堆端点配置。如果 openrig 支持运行时切换，那就更方便了，不用重启代理服务。

我个人的习惯是：日常写代码用 coding 组，遇到需要长上下文理解的任务切到 general 组，快速问答用 fast 组。这种分层策略能兼顾质量和速度。

5. 常见问题排查与避坑经验

5.1 配置解析失败的典型原因

yaml 配置解析失败是最常见的问题，没有之一。我整理了一个排查表：

这里重点说缩进问题。yaml 用缩进表示层级，同一层级的字段缩进必须完全一致。我见过有人从不同地方复制配置片段，有的用 2 空格，有的用 4 空格，拼在一起就乱了。建议整个配置文件统一用 2 空格缩进，编辑器里开启“显示空白字符”，一眼就能看出问题。

5.2 代理连接失败的排查思路

代理连不上，排查要按层次来。先确认 openrig 代理服务本身有没有起来：

curl http://localhost:8787/health

如果有健康检查端点，能返回就说明代理活着。然后确认下游模型服务是否可达：

curl http://localhost:1234/v1/models

如果这一步失败，问题在模型服务，不在 openrig。如果模型服务正常但代理转发失败，检查配置里的 endpoint 地址是否正确，端口有没有写错，路径有没有多余或缺失的斜杠。

还有一个隐蔽的问题：端口冲突。如果 8787 被别的程序占了，openrig 启动会失败或者行为异常。用lsof -i :8787看看端口占用情况，换个端口就行。

5.3 工具端报错的定位方法

claude code 或 codex 那边报错，信息往往很模糊，比如“请求失败”“无法连接”。这时候要看 openrig 的日志。把logLevel设成debug，日志里会记录每个请求的完整信息——请求地址、请求头、请求体、响应状态、响应体。对照日志就能定位问题出在哪一环。

我遇到过一个典型问题：claude code 报“认证失败”，但本地模型根本不需要认证。查日志发现，claude code 默认会带一个认证头，代理层原样转发给了本地服务，本地服务不认识这个头就拒绝了。解决办法是在代理配置里加一条规则，把不需要的认证头剥掉：

proxy: stripHeaders: - authorization - x-api-key

这种问题不看日志根本想不到，所以调试阶段一定要开 debug 日志。

5.4 性能与稳定性优化建议

跑通之后，还要考虑稳定性和性能。几个实操建议。

第一，给代理层加超时设置。本地模型响应可能很慢，如果代理层没有合理的超时，请求会一直挂着。但超时也不能太短，大模型生成长文本本来就需要时间。我一般设 120 秒起步，具体看模型速度。

第二，注意内存占用。node.js 处理流式响应时，如果流没有正确关闭，内存会慢慢涨。长时间运行后如果发现内存异常，检查是不是有流泄漏。用--max-old-space-size参数限制 node 堆内存，配合进程监控，能及早发现问题。

第三，日志轮转。debug 日志写多了会占满磁盘，生产环境要用日志轮转工具，或者定期清理。openrig 如果支持日志文件大小限制，配置上。

第四，配置版本管理。把 openrig 的 yaml 配置纳入 git 管理，每次改动都有记录。团队协作时，配置变更走 review 流程，避免有人改错了影响所有人。

6. 进阶玩法与扩展思路

6.1 团队共享配置的落地方案

团队里如果多个人用 AI 编程工具，配置统一是个大问题。我的做法是建一个内部仓库，放一份基准 openrig 配置，每个人 clone 下来后，用本地覆盖文件做个性化调整。基准配置里定义好团队统一的模型端点、代理规则、日志规范，个人覆盖文件里只放自己的认证信息和偏好设置。

openrig 如果支持配置继承（比如extends字段），那就更优雅了：

# 个人配置 extends: ./team-base.yaml tools: claude-code: auth: token: ${MY_TOKEN}

这样团队基准配置更新后，个人只需要 pull 一下就能同步，不用手动合并。

6.2 结合本地模型做离线开发

openrig 把 AI 编程工具接到本地模型后，最大的好处是离线可用。飞机上、网络差的地方、对数据隐私敏感的场景，本地模型都能顶上。虽然本地模型的能力和云端大模型有差距，但做代码补全、简单重构、写测试用例这些任务，够用了。

我实测下来，本地跑一个 7B 到 14B 的代码模型，配合 claude code 的文件读写能力，日常开发效率能提升不少。关键是响应速度快，没有网络延迟，而且不用担心代码片段被传到外部。

配置上要注意，本地模型的上下文窗口通常比云端小，claude code 如果一次性塞太多文件内容进去，会超出窗口。可以在配置里限制单次请求的 token 数，或者用 openrig 做请求裁剪。

6.3 配置模板与快速复用

折腾多了之后，我整理了几套配置模板，按场景分类：本地模型模板、第三方接口模板、混合模式模板。新项目直接复制对应模板，改几个字段就能用。

模板的价值在于把踩过的坑固化下来。比如本地模型模板里，认证头剥离、超时设置、流式响应容错这些都已经配好了，不用每次重新踩坑。我建议每个经常用 openrig 的人都维护自己的模板库，时间长了就是一笔财富。

配置模板还可以参数化，用环境变量占位，这样一套模板能适配不同的机器和账号。配合 dotenv 之类的工具，本地开发用.env文件，CI 环境用环境变量注入，一套配置到处跑。

6.4 后续可扩展的方向

openrig 这套思路还能往几个方向扩展。一是支持更多工具，除了 claude code 和 codex，其他 AI 编程助手如果也有类似的配置需求，都可以纳入统一管理。二是增强代理层的可观测性，加指标采集，统计每个工具的请求量、响应时间、错误率，方便优化。三是做配置的图形化管理，对不习惯手写 yaml 的人友好一些。

不过扩展归扩展，核心还是那句话：openrig 的价值在于用一层轻量的编排和代理，把散落的 AI 编程工具统一管起来。理解了这一点，怎么扩展都不会跑偏。

我在实际使用中最大的体会是：这类工具的价值不在于功能多花哨，而在于稳定和省心。配置一次，长期受益，把折腾环境的时间省下来写代码，这才是正经事。