如何为 OpenClaude 新增一个模型网关（Gateway Descriptor）？-北京尧图网络

如何为 OpenClaude 新增一个模型网关Gateway Descriptor【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude这篇文章面向 OpenClaude 的集成系统贡献者解决一个具体任务把一条「以自身 endpoint 契约托管、代理或聚合模型」的路由例如托管的 OpenAI 兼容网关、Ollama/LM Studio 这类本地路由、混合第三方品牌的聚合网关接入 OpenClaude。完成后的结果是新增一个位于src/integrations/gateways/下的描述符文件运行bun run integrations:generate后生成产物自动同步 loader、兼容映射、preset 类型和 provider UI 元数据。整个过程不需要手工编辑注册逻辑。适用前提你已经有 OpenClaude 仓库的本地检出并安装好bun文档中所有脚本均通过bun run调用你确认要接入的路由确实符合网关形态而不是第一方厂商直连 API 或 Anthropic 原生代理后两者在 add-vendor.md 和 add-anthropic-proxy.md 中分别描述。官方操作指南在 add-gateway.md配套参考样例在 reference-samples.mdPR 前检查清单在 common-pitfalls.md。什么时候该用网关描述符按文档的规则满足以下情况之一时才添加 gateway descriptor一条拥有自己 base URL 和鉴权契约的托管 OpenAI 兼容路由Ollama、LM Studio 一类的本地路由混合第三方品牌/模型的聚合路由需要发现元数据、发现缓存或 readiness 探测的路由。如果路由是规范的厂商直连 API应使用defineVendor而不是defineGateway如果路由以 Anthropic 风格 env 契约接收 Anthropic 原生流量应使用defineAnthropicProxy。描述符类型选错是 common-pitfalls.md 中列出的第一类错误。文件布局描述符文件放在src/integrations/gateways/id.tsid是网关的稳定标识例如仓库中已有的ollama、llmtr对应 ollama.ts、llmtr.ts。只有当目录catalog/发现规则大到值得拆分时才新增伴生文件src/integrations/gateways/id.models.ts仓库中的llmtr.models.ts就是这种两文件模式。编写规则来自 how-to 文档的 Authoring rules使用src/integrations/define.ts提供的defineGateway和defineCatalog辅助函数描述符文件export default导出的就是 gateway 描述符本身伴生*.models.ts默认导出 catalog不要在贡献者编写的描述符文件里调用registerGateway(...)注册由 loadersrc/integrations/index.ts拥有不要使用已移除的遗留字段targetVendorId、isOpenAICompatible、面向路由的网关classification。编写一个单文件网关描述符最短主路径下面这个例子直接来自官方文档的「one-file example」用于一条只托管自家模型的 OpenAI 兼容托管网关。文档明确说明这类样例中的 id、env 变量、URL 均为示意值落地前必须替换成真实路由的值import { defineCatalog, defineGateway } from ../define.js const catalog defineCatalog({ source: static, models: [ { id: acme-hosted-fast, apiName: acme-hosted-fast, label: Acme Hosted Fast, modelDescriptorId: acme-hosted-fast, }, { id: acme-hosted-pro, apiName: acme-hosted-pro, label: Acme Hosted Pro, modelDescriptorId: acme-hosted-pro, capabilities: { supportsReasoning: true, }, notes: Practical input limit is lower than the full context window., }, ], }) export default defineGateway({ id: acme-hosted, label: Acme Hosted, category: hosted, defaultBaseUrl: https://gateway.acme.example/v1, defaultModel: acme-hosted-fast, supportsModelRouting: true, setup: { requiresAuth: true, authMode: api-key, credentialEnvVars: [ACME_HOSTED_API_KEY], }, transportConfig: { kind: openai-compatible, openaiShim: { headers: { X-Acme-Client: openclaude, }, supportsApiFormatSelection: false, supportsAuthHeaders: true, ui: { showAuthHeader: false, showAuthHeaderValue: false, showCustomHeaders: true, }, // Optional: use a non-Authorization default auth header. defaultAuthHeader: { name: api-key, scheme: raw }, // Optional: restrict Responses API mode to model ids with these prefixes. responsesApiModelPrefixes: [gpt-], maxTokensField: max_completion_tokens, }, }, preset: { id: acme-hosted, description: Acme Hosted gateway, vendorId: openai, apiKeyEnvVars: [ACME_HOSTED_API_KEY], }, catalog, usage: { supported: false, }, })几个关键字段的用途均以文档说明为准transportConfig.kind是路由契约运行时靠它选择传输族而不是categorycategory只是可选的分组/展示元数据local/hosted/aggregatingdefaultModel一次性声明路由默认模型不要在 catalog 条目里再加default/recommended标记setup声明鉴权方式credentialEnvVars是预设流程收集 API key 时的环境变量名usage: { supported: false }表示该路由当前不支持/usage只有路由确实具备当前运行时支持时才声明supported: true见 common-pitfalls.md 的 Pitfall 10。openaiShim下的三个开关控制/provider add和/provider edit暴露哪些字段supportsApiFormatSelection: false时不暴露 API mode 选择器——适合描述符拥有固定 API 契约的托管或本地路由为true留给允许用户自选 API 面的宽泛自定义网关supportsAuthHeaders: false时只暴露路由常规凭据字段为true时启用头定制鉴权头名、值、任意自定义头再由ui.showAuthHeader/showAuthHeaderValue/showCustomHeaders决定具体哪几个提示可见maxTokensField在路由对 max token 字段严格时必须显式声明max_completion_tokens用于较新的托管 OpenAI 风格契约max_tokens用于本地、legacy 形态或拒绝新字段的提供方。startup块用于 readiness 与自动探测提示例如autoDetectable: true和probeReadiness: openai-compatible-models。注意文档提醒当discoveryRefreshMode: startup与openai-compatible-modelsreadiness 探测发起的是同一个请求时会成倍增加启动流量应避免两者同时配置。选择传输族transportConfig.kind决定路由契约可选值在 overview.md 中列举为transportConfig: { kind: openai-compatible, openaiShim: { supportsApiFormatSelection: false, supportsAuthHeaders: false, }, }openai-compatible路由说 OpenAI 兼容的请求/响应契约localOllama、LM Studio 一类的本地路由通常配maxTokensField: max_tokensanthropic-proxy真正接收 Anthropic 原生流量的网关形态路由。文档同时指出真实的 Anthropic 原生第三方路由更应走专门的 anthropic-proxy 指南传输族始终来自transportConfig.kind而不是网关专属兼容标志。不要用自定义头去替代传输族的选择——头属于openaiShim族属于kind。选择 catalog 策略按路由的目录形态三选一catalog.source适用条件static发现不可用或不必要目录固定的小型托管路由dynamic完全依赖运行时发现本地路由或频繁变化的提供方目录hybrid聚合器curated 默认条目要常驻其余由发现补齐当 catalog 需要发现时配套声明三个字段discoveryCacheTtl使用人类可读 TTL30m目录变化快、1h中等活跃的托管路由、1d稳定的托管/本地路由discoveryRefreshModemanual易抖动/限流提供方只按需刷新、on-openpicker 每次打开都尝试取新列表、background-if-stale托管网关的常规选择缓存模型立即可见、startup探测成本低的快速本地路由allowManualRefresh: true才支持/model refresh与 picker 内刷新共享发现缓存会在刷新失败或过期时继续展示 curated 条目。一个常见分拆鉴权的推理路由如果暴露了公共模型列表端点设catalog.discovery.requiresAuth: false同时保持setup.requiresAuth开启OpenRouter 和 Gitlawb Opengateway 就是这个模式列模型免 key推理要 key。目录或发现规则很大时按两文件模式拆分id.models.ts用defineCatalog导出 catalogid.ts用import catalog from ./id.models.js引入并传给defineGateway。文档给出的 hybrid 示例galaxy.models.ts/galaxy.ts完整展示了source: hybrid、discoveryCacheTtl: 1h、discoveryRefreshMode: background-if-stale与allowManualRefresh: true的组合可参照 reference-samples.md 的 Sample 3本地动态发现和 Sample 4两文件 hybrid。混合目录中若同一逻辑模型挂在共享模型描述符上用该模型描述符的providerModelMap记录各路由的具体 API 名。注意边界providerModelMap只负责元数据复用路由可用性仍然由路由自己的 catalog 决定。另外涉及 reasoning 控制时capabilities.supportsReasoning保持描述性元数据即可/effort可控的reasoning元数据要加在每个 catalog 条目上而不是网关级别且改动前先读 reasoning-effort.md。让网关出现在预设流程中可选分支只有当网关要在/provider等预设驱动流程中作为用户可选路由出现时才添加preset块并设置preset.vendorId让兼容/profile 辅助函数知道该网关属于哪个 vendor 契约preset: { id: acme-hosted, description: Acme Hosted gateway, vendorId: openai, apiKeyEnvVars: [ACME_HOSTED_API_KEY], }若预设 picker 需要展示标签可在preset.badge中声明overview.md 中说明这可避免在src/components/ProviderManager.tsx里硬编码 badge 逻辑。预设排序不手工配置由生成的 manifest 自动处理不需要在描述符里操心顺序。重新生成产物并验证描述符写完后运行bun run integrations:generate该脚本定义在 package.json 的 scripts 中实际执行scripts/generate-integrations-artifacts.ts让src/integrations/generated/integrationArtifacts.generated.ts同步 loader、兼容映射、preset 类型和 provider UI 元数据。正常网关接入是增量的改描述符文件、按需加preset块、跑生成命令不需要去手工编辑src/integrations/compatibility.ts、src/integrations/profileResolver.ts、src/integrations/providerUiMetadata.ts或 preset 排序表——这些都属于生成产物的范畴common-pitfalls.md 的 Pitfall 13。验证方式有两条检查生成物是否同步package.json提供了integrations:check脚本同一生成器加--check参数bun run integrations:generate --check它用于核对描述符与已提交的生成产物是否一致而不重新写文件。按官方 Verification checklist 自查来自 add-gateway.md 末尾描述符位于src/integrations/gateways/下网关只声明它实际提供的模型子集路由默认值只通过defaultModel声明一次transportConfig.kind承担路由契约category仅作分组/展示需要发现的路由声明了正确的 cache TTL、refresh mode 与手动刷新行为API mode、auth/header、token 字段行为在必要时显式声明用户可见的预设参与通过描述符preset元数据与再生成的产物表达而不是手写后续接线。此外由于描述符通过define*辅助函数保持类型化运行仓库既有的bun run typecheck即tsc --noEmit可以校验字段形状是否符合 descriptors.ts 当前定义的接口。提交前避开的坑以下错误模式在 common-pitfalls.md 中有专门条目写描述符时逐条对照描述符文件里调用registerGateway(...)等注册变更辅助函数使用targetVendorId、isOpenAICompatible或路由导向的classification等已移除字段用category做运行时路由决策把大段 hybrid catalog / 发现逻辑内联在id.ts里而不拆id.models.ts假设每个网关都暴露所有共享模型——路由 catalog 拥有可用性src/integrations/models/里的共享模型描述符只回答「模型是什么」在严格路由上遗漏openaiShim.maxTokensField。完成上述步骤并通过integrations:generate --check与自查清单后这条网关就按描述符时代的接入流程进入了 OpenClaude 的生成体系后续路由变更也只需继续维护描述符文件并重新生成。【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

如何为 OpenClaude 新增一个模型网关（Gateway Descriptor）？

相关推荐

Python实现积分系统动态控制算法与商业平衡

OpenFeign客户端内存泄漏问题分析与解决方案

ADHD成人实用操作系统：从神经特性到日常适配

更多资讯

LeetCode 784 字母大小写全排列（Letter Case Permutation）Go 双解法深度解析

制造业如何构建员工敢说真话的文化与机制

把不同品牌的摄像头接进同一个流媒体中枢：go2rtc 上手与排障

浏览器直接打开 docx，dwg 图纸在线看：kkFileView 文档在线预览快速上手指南（3 步跑通）

9款高效降AI率工具全解析：本科生论文必备

芯片制造文档管理中UMeditor的Word导入优化方案

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？