FAQ

🌐 Q: 为什么我的本地 OpenAPI 工具服务器无法从 WebUI 界面访问？

A: 如果您的工具服务器在本地运行（例如 http://localhost:8000），由于 CORS（跨源资源共享）策略，基于浏览器的客户端可能会被限制访问它。

请确保在您的 OpenAPI 服务器中显式启用 CORS 响应头。例如，如果您使用的是 FastAPI，可以添加以下代码：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 或者指定您的客户端源地址
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

此外，如果 Open WebUI 是通过 HTTPS 提供的（例如 https://yourdomain.com），您的本地服务器必须满足以下条件之一：

• 使用 HTTPS 从同一域名访问（例如 https://localhost:8000）。
• 或者运行在 localhost (127.0.0.1) 上，以允许浏览器放宽对本地开发的安全性限制。
• 否则，由于混合内容（mixed-content）规则，浏览器可能会阻止从 HTTPS 页面向 HTTP API 发送的不安全请求。

为了在生产环境中通过 HTTPS 安全地工作，您的 OpenAPI 服务器也必须通过 HTTPS 提供服务。

---

🚀 Q: 我的服务器实现需要使用 FastAPI 吗？

A: 不需要！虽然我们的参考实现是用 FastAPI 编写的，以便于清晰和易用，但您可以使用任何能生成有效 OpenAPI (Swagger) 规范的框架或语言。一些常见的选择包括：

• FastAPI (Python)
• Flask + Flask-RESTX (Python)
• Express + Swagger UI (JavaScript/Node)
• Spring Boot (Java)
• 结合 Swag 或 Echo 的 Go

关键是确保您的服务器暴露一个有效的 OpenAPI Schema，并且它通过 HTTP(S) 进行通信。 为所有端点设置一个自定义的 operationId 非常重要。

---

🚀 Q: 为什么选择 OpenAPI 而不是 MCP？

A: 在大多数实际场景中，OpenAPI 因其简单性、工具生态系统、稳定性和开发者友好性而胜过 MCP。原因如下：

• ✅ 复用您现有的代码：如果您以前构建过 REST API，那么您的大部分工作已经完成了——您不需要重写您的逻辑。只需定义一个符合规范的 OpenAPI Spec，并将您当前的代码暴露为工具服务器即可。

  如果使用 MCP，您必须在自定义协议层内重新实现您的工具逻辑，这会导致重复工作并增加了需要维护的系统复杂度。

• 💼 更少的维护与调试：OpenAPI 自然地融入了现代开发工作流。您可以使用 Postman 测试端点，使用内置 API 检查日志，使用成熟的生态系统工具轻松排查故障——而且通常根本不需要修改您的核心应用程序。

  MCP 引入了新的传输层、Schema 解析和运行时的一些奇特行为，所有这些都必须手动调试。

• 🌍 基于标准：OpenAPI 在整个科技行业被广泛采用。其定义良好的结构意味着工具、智能体（agents）和服务器可以立即互操作，无需特殊的桥接或转换。

• 🧰 更好的工具支持：有整个支撑 OpenAPI 的工具体系——自动客户端/服务器生成、文档、验证、Mock、测试，甚至安全审计工具。

• 🔐 一流的安全支持：OpenAPI 包含对 OAuth2、JWTs、API Keys 和 HTTPS 的原生支持——这使得使用常用库 and 标准构建安全端点变得更加容易。

• 🧠 更多开发者已经熟知它：使用 OpenAPI 意味着您正在使用后端团队、前端开发人员、DevOps 和产品工程师已经熟悉的语言。不需要学习曲线或昂贵的入职培训。

• 🔄 面向未来且易于扩展：OpenAPI 随 API 标准而演进，专为向前兼容而设计。相比之下，MCP 的标准化程度较低——通常需要随着周边生态系统的变化而进行更改。

底部结论（Bottom line）：OpenAPI 让您能够以更少的精力、更少的代码重复和更少的意外来完成更多的工作。这是一种生产就绪、对开发人员友好的为 LLM 工具赋能的途径——而无需从头重建一切。

---

🔐 Q: 如何保护我的 OpenAPI 工具服务器的安全？

A: OpenAPI 支持行业标准的安全机制，例如：

• OAuth 2.0
• API Key 响应头
• JWT (JSON Web Token)
• Basic Auth（基本认证）

在生产环境中使用 HTTPS 以加密传输中的数据，并根据需要使用适当的身份验证/授权方法限制端点。您可以使用 securitySchemes 字段直接将这些内容合并到您的 OpenAPI Schema 中。

---

❓ Q: 我可以使用 OpenAPI 工具服务器构建什么样式的工具？

A: 只要它可以通过 REST API 暴露，您就可以构建它。常见的工具类型包括：

• 文件系统操作（读写文件、列出目录）
• Git 和文档仓库访问
• 数据库查询或 Schema 探索
• 网页抓取或摘要生成器
• 外部 SaaS 集成（例如 Salesforce, Jira, Slack）
• LLM 附加的 Memory 存储 / RAG 组件
• 暴露给您智能体（agent）的安全内部微服务

---

🔌 Q: 我可以同时运行多个工具服务器吗？

A: 当然可以。每个工具服务器独立运行并暴露自己的 OpenAPI Schema。您的智能体（agent）配置可以指向多个工具服务器，允许您根据需要进行混合和匹配。

这没有限制——只需确保每个服务器运行在自己的端口或地址上，并且能被智能体宿主机访问到。

---

🧪 Q: 如何在将工具服务器连接到 LLM 智能体之前对其进行测试？

A: 您可以使用以下方式测试您的 OpenAPI 工具服务器：

• Swagger UI 或 ReDoc（默认内置于 FastAPI 中）
• Postman 或 Insomnia
• 命令行中的 curl 或 httpie
• Python 的 requests 模块
• OpenAPI 验证器和 Mock 工具

一旦通过验证，您就可以将工具服务器注册到 LLM 智能体中，或通过 Open WebUI 注册。

---

🛠️ Q: 我可以扩展或自定义参考服务器吗？

A: 可以的！servers/ 目录中的所有服务器都被构建为简单的模板。您可以 Fork 并修改它们以：

• 添加新的端点和业务逻辑
• 集成身份验证
• 更改响应格式
• 连接到新服务或内部 API
• 通过 Docker, Kubernetes 或任何云主机进行部署

---

🌍 Q: 我可以在 AWS 或 GCP 等云平台上运行 OpenAPI 工具服务器吗？

A: 可以。这些服务器是纯粹的 HTTP 服务。您可以将它们部署为：

• AWS Lambda 结合 API Gateway（无服务器）
• EC2 或 GCP Compute Engine 实例
• GKE/EKS/AKS 中的 Kubernetes 服务
• Cloud Run 或 App Engine
• Render, Railway, Heroku 等

只需确保它们已安全配置，并且在智能体或用户需要时可以通过公共网络访问（或通过 VPN）。

---

🧪 Q: 如果我已经有一个现有的 MCP 服务器该怎么办？

A: 好消息！您可以使用我们的 MCP 到 OpenAPI 桥接器：mcpo，现在将您现有的基于 MCP 的工具暴露为兼容 OpenAPI 的 API 比以往任何时候都更容易。无需重写，没有烦恼——即插即用！🚀

如果您已经使用 MCP 协议构建了工具，mcpo 可以帮助您立即解锁与 Open WebUI 和任何基于 OpenAPI 的智能体的兼容性——帮助您辛苦完成的成果保持可访问性，并面向未来。

请查看文档中可选的桥接至 MCP 部分以获取设置指南。

快速开始：

uvx mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York

✨ 就这么简单——您的 MCP 服务器现在已准备好对接 OpenAPI！

---

🗂️ Q: 一个 OpenAPI 服务器可以实现多个工具吗？

A: 可以。单个 OpenAPI 服务器可以提供分组在不同端点下的多个相关能力。例如，一个文档服务器可以提供搜索、上传、OCR 和摘要功能——所有这些都在一个 Schema 中。

如果您更喜欢隔离性和灵活性，您也可以通过为每个工具创建一个 OpenAPI 服务器来完全实现模块化。

---

🙋 还有更多问题？访问 GitHub 讨论区以获取社区的帮助和反馈： 👉 社区讨论区