1. 项目概述与背景如果你和我一样曾经为了给 LibreChat 这类开源 AI 聊天客户端寻找可用的 ChatGPT 插件而焦头烂额那你一定能理解我创建chatgpt-plugins这个仓库的初衷。市面上虽然有不少插件列表但要么信息不全要么格式不友好尤其是当你需要将这些插件集成到自己的本地或私有化部署的 AI 平台时一个结构清晰、易于管理的清单就显得至关重要。我最初发现copilot-us维护的列表是目前最全面的这一点必须感谢原作者的辛勤工作。但它的数据是以一个巨大的单一 JSON 文件形式存在的。对于开发者来说尤其是想集成到 LibreChat 这样的系统中这种格式并不理想。LibreChat 等工具通常期望每个插件都有一个独立的ai-plugin.json清单文件存放在特定的.well-known目录下以便自动发现和加载。因此我的工作就是将那个庞大的 JSON “数据块” 拆解、清洗、整理转换成一个个独立的清单文件。这个仓库的目标就是成为一个集中、规范、且对开发者友好的 ChatGPT 插件清单库。无论你是想研究插件生态还是想为自己的 AI 应用快速集成功能这里都希望能为你节省大量搜索和整理的时间。2. 核心价值为什么需要独立的插件清单你可能会有疑问OpenAI 官方不是有插件商店吗为什么还要费劲维护一个第三方清单这背后有几个非常实际的考量尤其是在企业级或自定义部署的场景下。2.1 官方商店的局限性首先OpenAI 官方的插件商店主要服务于 ChatGPT Plus 用户其使用和安装流程是绑定在 OpenAI 平台上的。这意味着平台依赖性强你无法脱离 ChatGPT 的 Web 界面或官方 API 来使用这些插件。无法离线或私有化部署对于需要在内网环境、或对数据隐私有严格要求的公司直接使用官方商店的插件是不现实的。审查与可用性插件上架官方商店需要经过审核且开发者可能随时下架这对于构建一个长期稳定的、集成了特定插件功能的应用来说存在风险。2.2 开源与自托管平台的需求像 LibreChat 这样的开源项目其魅力在于赋予用户完全的控制权。你可以将它部署在自己的服务器上连接自己的 OpenAI API 密钥甚至微调自己的模型。在这种情况下用户自然也希望拥有对插件的同等控制权。一个本地的、可管理的插件清单文件集合使得以下操作成为可能自主集成开发者可以自由选择将哪些插件功能打包进自己的应用。免去手动配置用户无需逐个查找插件的清单 URL 和 API 描述只需将文件放入指定目录即可。版本管理与归档可以像管理代码依赖一样管理插件的版本和清单定义即使原插件服务下线其接口定义依然可用作参考。安全审计可以仔细审查每个插件清单中声明的 API 端点、认证方式、数据权限确保符合自身的安全策略。2.3 清单文件Manifest的核心作用一个标准的 ChatGPT 插件清单文件通常命名为ai-plugin.json是一个 JSON 文件它扮演着“插件说明书”的角色。它必须包含几个关键部分schema_version: 清单格式的版本号。name_for_model: 模型识别插件时使用的名称。name_for_human: 展示给用户的插件名称。description_for_model: 给 AI 模型的指令告诉它这个插件是做什么的、何时以及如何调用。description_for_human: 给用户看的插件描述。auth: 认证配置如无认证、API 密钥、OAuth 等。api: 指向 OpenAPI 规范文件的 URL该文件详细定义了插件的所有可用接口。logo_url: 插件的图标。contact_email: 开发者联系方式。legal_info_url: 法律条款链接。这个文件通常需要托管在一个可通过 HTTPS 访问的、路径为/.well-known/ai-plugin.json的 URL 下。对于 LibreChat 这类工具它简化了这个过程你只需要将ai-plugin.json文件或按特定规则命名的文件放在本地服务器的对应目录如/api/app/clients/tools/.well-known/它就能被识别和加载。因此chatgpt-plugins仓库所做的本质上是在构建一个“插件定义”的离线仓库为开源生态提供了基础设施级别的支持。3. 仓库结构解析与使用指南理解了“为什么”之后我们来看看“怎么用”。这个仓库的结构设计旨在最大化便利性。3.1 仓库目录结构仓库的核心是manifests/目录。我按照插件名称或一个合理的标识为每个插件创建了独立的 JSON 文件。例如manifests/askyourpdf.jsonmanifests/scholarai.jsonmanifests/wolfram.json这种扁平化的结构有几个好处一目了然通过文件名就能快速定位插件。易于脚本处理你可以写一个简单的脚本遍历整个manifests/目录批量处理所有文件。便于版本控制Git 可以清晰地追踪每个插件清单的变更历史。3.2 如何用于 LibreChat这是最直接的使用场景。根据 LibreChat 的文档和社区实践通常的集成步骤如下克隆或下载仓库git clone https://github.com/izzoa/chatgpt-plugins.git或者直接下载 ZIP 包。定位 LibreChat 的插件目录这取决于你的部署方式。Docker 部署如果你通过 Docker 运行 LibreChat你需要将清单文件挂载到容器内的特定路径。通常这个路径在容器内是/app/api/app/clients/tools/.well-known/。源码部署如果你直接运行源码路径就是项目根目录下的/api/app/clients/tools/.well-known/。复制清单文件将manifests/目录下你需要的.json文件复制到上述的.well-known/目录中。你可以全部复制也可以选择性复制。# 示例复制所有清单文件到 LibreChat 的对应目录假设你位于仓库根目录 cp manifests/*.json /path/to/your/librechat/api/app/clients/tools/.well-known/重启服务为了让 LibreChat 加载新的插件清单你需要重启服务。Docker:docker-compose restart或重启相关容器。源码: 重启 Node.js 进程。在界面中启用重启后在 LibreChat 的界面上你应该能在插件选择列表中看到新添加的插件。勾选即可启用。重要提示仅仅复制清单文件并不意味着插件就能直接工作。清单文件中的api.url字段指向的是插件开发者提供的真实 API 服务地址。如果该服务需要认证auth字段你通常还需要在 LibreChat 的配置界面或环境变量中配置相应的 API 密钥。有些插件服务可能是免费公开的有些则可能需要注册获取密钥。请务必阅读插件清单中auth部分的说明。3.3 如何用于其他平台或自定义开发如果你不是在用 LibreChat而是在开发自己的 AI 应用这个仓库同样极具参考价值。作为接口定义参考你可以直接研究这些ai-plugin.json文件学习 ChatGPT 插件标准的实现方式特别是description_for_model的编写技巧这对于指导 AI 如何正确使用你的插件至关重要。构建自己的插件发现服务你可以以这个仓库为数据源构建一个内部的插件市场或发现服务。定期同步此仓库解析清单为你平台上的用户提供可安装的插件列表。测试与验证在开发自己的插件时可以用这些公开的清单文件作为测试用例验证你的应用是否能正确解析和加载标准格式的插件。3.4 数据维护与更新策略一个仓库的价值在于其持续性和准确性。chatgpt-plugins的数据主要来源于copilot-us的原始列表但我会进行以下处理和维护格式标准化确保每个 JSON 文件符合 OpenAI 的插件清单规范。链接有效性检查定期或通过自动化脚本检查清单中api.urlOpenAPI 规范地址和logo_url等外链是否依然有效。失效的链接会在仓库的 Issues 或 Readme 中被标记。社区贡献鼓励开发者提交新的插件清单或修正现有清单的错误。通过 Pull Request 流程来保证质量。元信息补充在仓库的 README 或一个单独的索引文件中像源项目一样以表格形式列出所有插件并补充如“是否需要 API Key”、“服务状态”等实用信息帮助用户快速筛选。4. 实操从清单到可运行插件的深度解析仅仅把文件放进去可能还不够。要让一个插件真正在 LibreChat 或类似平台中工作起来我们需要深入理解清单文件与后端服务的关系。让我们以一个具体的插件为例比如askyourpdf.json。4.1 解剖一个插件清单我们打开manifests/askyourpdf.json会看到类似如下的结构已简化{ schema_version: v1, name_for_model: askyourpdf, name_for_human: AskYourPDF, description_for_model: This plugin allows you to interact with PDF documents. You can extract text, summarize, or answer questions based on the content of a PDF. The user must provide a PDF file or a publicly accessible PDF URL., description_for_human: Unlock the power of your PDFs! Upload a document and ask questions, get summaries, or find specific information., auth: { type: service_http, authorization_type: bearer, verification_tokens: { openai: your_verification_token_here // 通常由插件服务方提供 } }, api: { type: openapi, url: https://api.askyourpdf.com/.well-known/openapi.yaml }, logo_url: https://askyourpdf.com/logo.png, contact_email: supportaskyourpdf.com, legal_info_url: https://askyourpdf.com/terms }关键字段解读description_for_model这是给 AI 看的“工作说明书”。它必须清晰、无歧义地说明插件的功能、输入要求和输出格式。编写良好的描述能极大提升模型调用插件的准确率。auth定义了认证方式。service_http和bearer类型意味着调用 API 时需要在 HTTP 请求头中添加Authorization: Bearer API_KEY。这个 API Key 需要用户从 AskYourPDF 服务提供商处获取并配置到 LibreChat 中。api.url指向一个 OpenAPI (Swagger) 规范文件。这个 YAML 或 JSON 文件详细描述了所有可用的端点如/upload,/query、请求方法、参数和响应格式。LibreChat 在加载插件时会读取这个文件从而知道如何构造请求。4.2 在 LibreChat 中配置插件认证这是最关键也最容易出错的一步。以 AskYourPDF 为例假设你已在其官网注册并获得了 API Keysk-xyz123。环境变量配置推荐对于 Docker 部署最规范的方式是通过环境变量传递密钥。你需要在docker-compose.yml或.env文件中添加配置。LibreChat 通常使用PLUGIN_PLUGIN_NAME_KEY的格式。# 在 docker-compose.yml 的 services.api.environment 部分添加 environment: - PLUGIN_ASKYOURPDF_KEYsk-xyz123重启容器后LibreChat 会自动将此密钥用于该插件的所有请求。界面配置某些版本的 LibreChat 或在某些配置下也可以在管理员界面或用户设置中直接填写插件的 API Key。验证配置配置完成后在聊天界面尝试使用该插件。例如上传一个 PDF 或输入一个 PDF 链接然后提问。观察网络请求浏览器开发者工具的 Network 标签页确认发出的请求头中是否包含了正确的Authorization: Bearer sk-xyz123。如果返回 401 错误说明认证失败需要检查密钥是否正确以及配置是否生效。4.3 处理插件服务不可用或变更你可能会遇到插件无法使用的情况通常有以下几个原因服务端下线或变更插件开发者可能停止了服务或者更改了 API 端点。此时即使清单文件正确请求也会失败返回 404、500 等错误。解决方案是检查该插件的官方网站或状态页。在仓库的 Issues 中查看是否有其他人报告同样问题。考虑寻找替代插件。OpenAPI 规范 URL 失效如果api.url指向的 OpenAPI 文件无法访问LibreChat 可能无法正确加载插件功能。你可以尝试手动访问该 URL 进行验证。CORS 问题如果插件服务端没有正确配置 CORS (跨域资源共享)从前端浏览器发起的请求可能会被拦截。不过由于 LibreChat 的后端服务器通常作为代理来调用插件 API这个问题大多发生在后端对用户透明。如果遇到 CORS 错误可能需要插件开发者调整服务端配置。一个实用的排查流程确认插件已在 LibreChat 界面中成功勾选并启用。尝试进行一个简单的插件操作。打开浏览器开发者工具 - Network筛选fetch或xhr请求。找到向插件域名发起的请求查看其 Request Headers 和 Response。根据 HTTP 状态码和响应信息判断问题所在认证失败、404、服务器错误等。5. 高级应用与二次开发对于开发者而言这个仓库的价值远不止于“即插即用”。它更是一个学习和构建的宝库。5.1 基于现有清单开发自定义插件代理假设你非常喜欢某个插件如 WolframAlpha的功能但其服务在国内访问不稳定或者你希望在其基础上增加一些自定义逻辑如缓存、日志、数据格式化。你可以这样做研究清单与 API 规范从本仓库找到wolfram.json查看其api.url指向的 OpenAPI 规范。搭建代理服务使用 Node.js (Express)、Python (FastAPI) 等任何你熟悉的语言搭建一个简单的 HTTP 代理服务。复制接口定义让你的代理服务实现与原始插件相同的 API 接口路径、参数、响应格式。这可以通过直接导入 OpenAPI 规范来辅助生成代码框架。添加代理逻辑在你的服务中接收来自 LibreChat 的请求然后可选进行请求参数的验证、转换或增强。将请求转发给原始的 WolframAlpha API附上你拥有的合法 API Key。可选对原始响应进行处理如缓存结果、简化数据、翻译内容。将处理后的响应返回给 LibreChat。创建自定义清单为你自己的代理服务编写一个新的ai-plugin.json文件。将api.url指向你代理服务的 OpenAPI 规范地址并更新description_for_human等字段以作说明。部署与集成将你的代理服务部署上线并将自定义的清单文件放入 LibreChat 的.well-known目录。现在LibreChat 用户使用的就是你提供的、经过增强的“WolframAlpha”插件了。这种方式让你能完全控制插件的可用性、性能和功能非常适合企业级应用。5.2 构建插件管理与发现界面如果你在为一个团队或社区维护 LibreChat 实例可以基于这个仓库构建一个简单的内部管理界面。数据层将manifests/目录下的 JSON 文件信息解析并存入数据库如 SQLite 或 PostgreSQL每个插件作为一条记录字段包括名称、描述、认证方式、API URL、状态等。后台服务开发一个后台服务定期同步chatgpt-plugins仓库的更新并检测每个插件 API 的健康状态通过心跳检测或模拟简单请求。管理界面提供一个 Web 界面展示所有可用插件并允许管理员一键启用/禁用某个插件实际上是在 LibreChat 的.well-known目录中增删文件。批量配置插件的 API Key。查看插件的使用统计和健康状态。用户界面在 LibreChat 前端注入一个简单的插件市场标签页用户可以从管理员已启用的插件列表中自行选择添加到自己的聊天会话中。这样插件的管理就从手动操作文件变成了可视化的运维大大提升了效率。5.3 清单文件的规范化与质量检查在维护这样一个仓库时保证清单文件的质量非常重要。可以建立一些自动化检查JSON 语法验证使用jq或编程语言的 JSON 解析库确保每个文件都是有效的 JSON。Schema 验证根据 OpenAI 官方的插件清单 JSON Schema验证每个文件的结构和必填字段是否符合规范。链接存活检查定期对api.url和logo_url发起 HEAD 请求检查链接是否有效将失效的链接记录并标记。描述性检查可以设置简单的规则比如检查description_for_model是否过于简短可能无法有效指导 AI或者是否包含了关键的操作指令。将这些检查集成到 CI/CD 流程中例如 GitHub Actions每当有新的 Pull Request 提交时自动运行可以有效地维护仓库的数据质量。6. 常见问题与故障排除实录在实际使用和集成过程中我踩过不少坑。这里把一些典型问题和解决方案记录下来希望能帮你绕开这些弯路。6.1 插件加载失败LibreChat 界面不显示症状已将.json文件放入.well-known目录并重启服务但在聊天界面的插件列表中看不到新插件。可能原因与排查目录路径错误这是最常见的原因。再次确认文件是否放在了正确的、LibreChat 服务进程有读取权限的目录下。对于 Docker务必确认卷挂载volume mount的路径映射是否正确。文件权限问题在 Linux 服务器上确保nginx或node运行用户对.well-known目录及其下的文件有读取权限 (chmod -R 755 /path/to/.well-known)。清单文件格式错误JSON 文件可能存在语法错误。可以使用在线 JSON 校验工具或命令行jq . your-plugin.json来验证。一个常见的错误是末尾多余的逗号。服务未完全重启有时重启命令并未生效。尝试彻底停止服务后再启动或者查看应用日志是否有相关错误输出。LibreChat 版本不兼容较旧版本的 LibreChat 可能对清单文件的格式或存放位置有不同要求。查阅你所使用版本的官方文档。6.2 插件能显示但使用时报错如“插件调用失败”症状插件出现在列表中可以勾选但一旦尝试使用如发送涉及插件功能的请求聊天界面返回错误。可能原因与排查认证配置缺失或错误这是头号嫌疑犯。确认你已为该插件配置了正确的 API Key并且配置方式环境变量 vs 界面设置已被 LibreChat 正确读取。检查 LibreChat 服务端的日志里面通常会明确记录认证失败的信息。网络连通性问题插件服务端的 API 地址可能无法从你的 LibreChat 服务器访问被墙、服务器防火墙限制等。尝试在部署 LibreChat 的服务器上用curl命令测试是否能访问清单中api.url指向的 OpenAPI 规范地址。curl -I https://api.askyourpdf.com/.well-known/openapi.yaml插件服务已下线或限流插件本身的服务可能暂时不可用或已达到调用频率限制。访问该插件的官方网站查看状态或尝试其提供的演示接口。请求参数错误AI 模型根据description_for_model生成的请求参数可能不符合插件 API 的实际要求。这需要对比插件的 OpenAPI 规范来排查。作为临时方案你可以尝试在提问时用更清晰、更符合常规 API 调用的语言来描述你的需求。6.3 如何为私有或自研的插件创建清单场景你自己开发了一个内部工具并希望将它作为插件集成到 LibreChat 中。步骤开发 API 服务首先你的工具需要提供 HTTP API 接口并最好遵循 RESTful 风格。编写 OpenAPI 规范为你的 API 编写一个openapi.yaml或openapi.json文件。你可以使用 Swagger Editor 等工具来辅助。这个文件必须详细定义所有端点、参数、请求/响应体。创建ai-plugin.json参考本仓库中任何一份清单的格式。关键点name_for_model起一个简短、无空格、易于模型识别的名字如company_internal_tool。description_for_model这是最重要的部分。用清晰、具体的英文模型对英文理解更好描述功能。例如“Use this tool to query the internal employee database. When the user asks about employee information, department details, or office location, you MUST use this plugin. The required parameter isquery_string, which is the search keyword provided by the user.”auth如果只是内部使用可以设置为{“type”: “none”}。如果需要认证则配置相应的方式。api.url指向你托管 OpenAPI 规范文件的 URL必须可通过 HTTPS 访问且路径为/.well-known/openapi.yaml。托管清单文件将ai-plugin.json文件托管在你的 API 服务器的/.well-known/路径下确保可通过https://your-api.com/.well-known/ai-plugin.json访问。在 LibreChat 中使用现在你可以通过两种方式添加你的插件远程加载在 LibreChat 的插件设置中直接输入你的清单文件 URL (https://your-api.com/.well-known/ai-plugin.json)。本地加载将你的ai-plugin.json文件下载下来改个名避免冲突放入 LibreChat 的本地.well-known目录。6.4 插件响应慢或超时症状调用插件后需要等待很长时间才有回复甚至超时。分析与优化网络延迟如果插件服务器在海外而你的 LibreChat 在国内网络延迟是主要因素。考虑使用上述的“代理服务”模式将代理部署在海外或网络优化较好的区域。插件服务性能某些免费的插件服务可能资源有限响应慢。考虑寻找替代插件或者如果该服务提供付费套餐升级可能改善性能。LibreChat 超时设置检查 LibreChat 服务端配置中是否有插件调用的超时时间设置适当调大如从 10 秒调到 30 秒。但这只是治标根本原因还是网络或服务端慢。请求内容过大例如通过插件上传一个非常大的 PDF 文件进行处理。尝试优化请求比如先提供文件链接而非直接上传二进制流如果插件支持或者对文件进行预处理压缩、分页。维护和使用这样一个插件仓库就像打理一个工具库。核心在于理解每个工具插件的说明书清单并确保它们与你自己的工作台LibreChat兼容。这个过程虽然有些繁琐但一旦跑通你将拥有一个高度定制化、功能强大且完全受控的 AI 助手环境。